Comprehender

Read your Python like a debugger — without running the debugger.

Pick a file or a function. Comprehender traces it (locally, in a sandboxed CPython-on-WASM runtime — your code never leaves your machine) and opens its answers as native editor tabs beside your code:

• debugger — the call tree as a foldable reading spine: every stepped line with its real values, shapes, and per-line math
• visualize — the run's tensors and arrays as inline pictures
• model — the architecture diagrams, for ML builds that ship them
• eli5 — a plain-words document explaining the file, generated with your own Anthropic API key (no server, no account — see Settings)
• flow — for ML files: a value ledger tracing every value the file creates — what it is made of, where every number came from, where it is parked, and who consumes it. Opens automatically whenever the traced code imports an ML library (torch, tensorflow, jax, sklearn, …)

Each answer is its own VS Code tab — debugger, visualize, and eli5 open together on one trace (set comprehender.modeTabs to change the set). Because they're real editor tabs, VS Code's own layout is the layout: drag one into another group, snap them into a 2×2 grid, tear one off into a floating window, keep the debugger beside your code and eli5 on the second monitor. Tabs on the same trace stay in sync wherever they land, and Comprehender: Open … Tab in the Command Palette brings back any one you closed.

Every click in an answer points back into your code: the real editor reveals and highlights the line. Moving your cursor in the editor scrolls the answers to that step.

Getting started

1. Open a Python file.
2. Click the ▷ comprehend CodeLens above any def/class — or right-click → Comprehend This File — or run Comprehender: Comprehend… from the Command Palette.
3. First trace boots the bundled Python runtime (~5–10 s); after that, traces are fast and cached until the code changes.

No account, no sign-in, no network needed for tracing.

The opening question

Launching without a target asks exactly one thing:

train.py is open right now — what should I comprehend?
▸ This entire file (train.py)
▸ A specific function or class in train.py…
▸ A different file…

Settings

Iterating on the prompts

Templates (*_deepseek.json, ml_mathflow.json) are re-read from explainAssetsDir on every eli5 run, and their bytes key the answer cache — edit, click eli5 again, done. explain.py edits need one Comprehender: Reload Runtime (it imports at boot). Extension/webview code edits: just ext-install at the repo root rebuilds, packages, and reinstalls in one command.

Notes

• The trace runs your code (the selected entry, with toy-sized inputs where it can) inside a WASM sandbox in the extension host — not in your Python environment, and with no access to it.
• Pure-Python + NumPy/SymPy code traces best. Imports the sandbox can't satisfy degrade honestly: the build says exactly which sections ran and which show structure only.
• The answer tab follows your VS Code theme automatically.

🤖 The extension embeds Pyodide (MPL-2.0), NumPy and SymPy (BSD-3-Clause), and TikZJax (LPPL 1.3c) — see THIRD-PARTY-NOTICES.md.