Adaptive

An adaptive tutor for unfamiliar code, inside VS Code. It learns how you learn, remembers what you already know, and explains the rest at your level — driven by a coding-agent CLI you already have, Claude Code by default. The code itself is highlighted step by step while the explanation and a map of every step live in a dedicated side bar — no chat window to cross-reference, no scrolling back to find where you were.

Built for the thing that actually costs time on an unfamiliar codebase: tracing one flow end to end, across files, without losing the thread.

• Draw it as a diagram — one click turns the flow you just read into a conventional architecture diagram: C4 Context/Container/Component, a UML sequence or class diagram, or a flowchart.
• Resize the explanation pane — drag the splitter to give the text or the step list more room; it remembers where you put it.
• Steps stream in as they're written — step 1 is readable in a few seconds instead of after the whole walkthrough finishes generating (Claude Code only; other agents show the walkthrough when the run finishes).
• Written for you, not to a word count — the profile you fill in once decides how much each step needs: what you already know gets a sentence, what is new to you gets as long as it takes to understand on the first read.
• Push back on any explanation — ✎ Clarify rewrites the one step or line you're reading from what you type, leaving the rest of the walkthrough untouched. Say it plainly ("stop using analogies") and it remembers, for every walkthrough after this one.
• Three detail levels — how closely it walks the code (a step per unit of behaviour, per function, or per function with the mechanics), not how much it says about each step. Line-by-line explanations are fetched only for the steps you actually open.
• A walkthrough history — every walkthrough and side-track explain is kept, and reopening one is free: it replays from local storage, with no new agent call.
• Side-tracks don't lose your place — explain any selection mid-flow, then click back to exactly where you were.
• Per-file orientation — when a flow first enters a file, you get two lines on what that file is and where it sits in the architecture.

Nine modes: guided per-file, trace-a-flow (you describe it), let-AI-pick-a-flow, big picture, architecture, project tour, code style, dependency explainer, and explain-selection.

→ User guide (GUIDE.md, shipped with the extension) — what each mode is for, how to get around, what costs an agent call, and troubleshooting. About five minutes.

Requirements

• A coding-agent CLI on your PATH, already logged in. Out of the box that is Claude Code (claude); codeWalkthrough.agent switches it to the Codex CLI, and any other agent works through codeWalkthrough.agentCommand — see Choosing the agent.
• For Claude Code, either a Claude subscription (claude login) or an Anthropic API key. The extension asks which you want the first time you use it; run Adaptive: Set Up Authentication to change it later. API keys go into VS Code's encrypted SecretStorage, never a file. Every other agent uses its own login, and is never asked about.
• VS Code 1.85+.

Install

From the VS Code Marketplace — search Adaptive in the Extensions view and press Install, or from a terminal:

code --install-extension AayushMotiani.code-walkthrough

Or download the .vsix directly and install it by hand:

curl -fsSL -o cw.vsix https://github.com/amotiani/code-walkthrough-releases/releases/latest/download/code-walkthrough.vsix && code --install-extension cw.vsix

# Windows PowerShell
iwr -Uri https://github.com/amotiani/code-walkthrough-releases/releases/latest/download/code-walkthrough.vsix -OutFile cw.vsix; code --install-extension cw.vsix

Then reload the VS Code window (Command Palette → Developer: Reload Window). That's it.

Ask an agent to install it

Paste this at any coding agent with shell access:

Install the Adaptive VS Code extension from https://github.com/amotiani/code-walkthrough-releases — follow its AGENTS.md.

That repo's AGENTS.md gives it the exact non-interactive commands, so it needs no further instructions from you.

Using it

Click the 💡 lightbulb icon in the editor title bar. That opens the Walkthroughs panel in the activity bar:

┌─ ADAPTIVE ───────────────┐
│ ➕ New Walkthrough        │
│ History            Clear │
│                          │
│ Today                    │
│  ▸ Flow: how does a ...  │
│  ▸ Explain: useAuth()    │
│ Yesterday                │
│  ▸ Project tour          │
└──────────────────────────┘

➕ New Walkthrough asks for a mode, then a detail level, and starts. As it runs, two things happen:

• The current step is highlighted in the code, tinted by what kind of line it is, with a boundary rule top and bottom.
• The Explanation view opens in the right-hand side bar with the step's title, its explanation, and a collapsible ▸ All steps (N) map — click any step to jump straight to it.

Past walkthroughs sit in the list below, grouped by day and titled with the prompt you typed. Clicking one reopens it exactly where you left off, for free. Hovering a row reveals a 📋 button that copies its prompt verbatim.

Keyboard

→ and ← work from the walkthrough side bars too, not just from the code, so you can read and step without clicking back into the editor first.

Every action is also a CodeLens button above the highlighted code. The status bar shows Chunk 3/12 (click to toggle mode) plus a live progress readout while an analysis is running (click to cancel).

Detail levels and cost

Chosen each time you start something. The level sets how closely the walkthrough walks the code, not how much it says about each step:

Every level explains each step in full: low means fewer steps, not thinner ones. How much a step needs is judged against the profile you filled in when you first ran it — what you already know gets a sentence, what's new to you gets as long as it takes. The bar is that you understand it on the first read, without having to go and ask someone.

At every level, line-by-line detail is generated only for steps you explicitly open (Enter, or the Walk through it line by line button at the end of a run). Nothing is fetched in the background — the extension never spends an agent call you didn't ask for.

Results are cached: single-file and flow walkthroughs are keyed to the file contents or the flow description, so re-running one over unchanged code is free and an edit correctly regenerates. Repo-wide modes cache for 24 hours. Reopening anything from history is always free.

When an explanation misses

Every step has a ✎ Clarify link at the top of the Explanation view. Click it, say what's wrong in your own words, and that explanation is rewritten — the rest of the walkthrough is left exactly as it was. In line-by-line mode it rewrites the single line you're on.

✎ Clarify  →  "what's a webview? explain it without assuming I know"
              "stop explaining things with analogies"
              "you skipped why the guard has to run before the fetch"

Two different things happen depending on what you typed. A question about the code, or a correction, just fixes that step. But if you said something about how you want things written, it's remembered and applied to every future walkthrough, in every project — and you get a one-click Undo right then, while you still remember typing it.

Adaptive: Edit My Writing Preferences lists everything it has learned, each shown with the words you originally used, so you can tell a preference you meant from one it over-read. Pick one to forget it, or add your own directly.

One thing it deliberately won't do: a preference can't become a length cap. "Too long" is taken as "you're padding me with things I already know" — so it cuts the padding and spends the space on what's actually new to you, rather than leaving you with an unanswered question.

Choosing the agent

The explanations are written by a coding-agent CLI running on your machine, and which one is a setting. Claude Code is the default and the one this extension is developed against — it is also the only one that streams, so steps appear one at a time instead of all at once when the run finishes.

Whichever you pick has to be installed, on your PATH, and already logged in; the extension never handles credentials for anything but Claude Code. Set codeWalkthrough.model if you want a specific model — left empty, each CLI uses its own default.

Any agent that can be run non-interactively works, whether or not it has a preset. Point codeWalkthrough.agentCommand at it and give the flags that put it in one-shot mode:

{
  "codeWalkthrough.agent": "custom",
  "codeWalkthrough.agentCommand": "hermes",
  "codeWalkthrough.agentArgs": ["--print", "--model", "${model}"]
}

The prompt is always written to the process's stdin, so agentArgs never has to carry it. The reply is read from stdout — a {"result": …} or {"response": …} envelope is unwrapped, and anything else is taken as the answer, so a plain-text CLI needs nothing special.

Only agents with an enforceable read-only boundary ship as presets. Anything else goes through custom, where you supply the flags — and if a preset flag is wrong for the version you have, codeWalkthrough.agentArgs overrides the whole argument list without waiting on a release.

Settings

Commands

All available from the Command Palette under Adaptive:

For AI agents

Point any coding agent with shell access at code-walkthrough-releases and it will find an AGENTS.md there with the exact non-interactive install commands — no further instructions needed from you.

Privacy

No telemetry, and this extension sends your code nowhere itself. Explanations are generated by a coding-agent CLI you install and authenticate; when you start a walkthrough the relevant source and your reader profile are handed to that CLI, which talks to whichever provider you configured. Your profile, writing preferences and walkthrough history are stored locally by VS Code. An API key, if you use one, goes into VS Code's encrypted SecretStorage.

License

Proprietary — see LICENSE. Free to install and use, including at work; not redistributable.