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 an
answer tab 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)
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 answer
to that step. Open a second Comprehender tab and split it with VS Code's own
editor groups — tabs on the same trace stay in sync.
Getting started
- Open a Python file.
- Click the ▷ comprehend CodeLens above any
def/class — or right-click
→ Comprehend This File — or run Comprehender: Comprehend… from the
Command Palette.
- 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
| Setting |
Default |
What it does |
comprehender.codeLens |
true |
the ▷ comprehend lenses above defs |
comprehender.maxFiles |
500 |
most workspace files shipped into a trace |
comprehender.traceTimeoutSeconds |
180 |
wall-clock cap per trace |
comprehender.serverUrl |
comprehender cloud |
where eli5 is generated (the deployment holds the key — no setup); empty switches to the direct lanes below |
comprehender.openrouterApiKey |
(empty) |
optional own OpenRouter key for the direct eli5 lane (used when serverUrl is empty) |
comprehender.model |
deepseek/deepseek-v4-flash |
OpenRouter model id for the direct eli5 lane |
comprehender.cloudUrl |
cloud /api/complete |
completion fallback for the direct lane when no key is set |
comprehender.explainAssetsDir |
(empty) |
your comprehender repo root: eli5 uses its live explain.py + prompt templates instead of the bundled copies |
Iterating on the prompts
Templates (*_deepseek.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.
