Install: VS Code Marketplace · Open VSX (Cursor, Windsurf, VSCodium)
English | 繁體中文
Note: The extension UI follows your VS Code display language (Traditional Chinese or English). Walk content (narration, quiz questions, etc.) is written by each walk's author and is shown as-is, unaffected by this setting.
The fastest way to actually understand someone else's code is to have a mentor sit next to you and walk you through it. CodeWalk brings that experience into the VS Code side panel.
CodeWalk reads a walkthrough file from your repo and guides you through it step by step: jumping to and highlighting the right lines, adding narration and glossary terms, and finishing with a quiz to check you actually understood it.
Useful for onboarding, picking up an unfamiliar module, sanity-checking a pile of AI-generated files, or getting a reviewer up to speed on a large diff before they review it.
1. Install
Search for CodeWalk in the VS Code Extensions panel. After installing, a path icon appears in the Activity Bar.
2. Prepare a walk
Create a .codewalk/ folder at your repo root and add a *.codewalk.json file (format below).
Don't want to write JSON by hand? Authoring walks has a prompt you can hand to any AI assistant — it covers three scopes: the whole codebase, the current git diff, or an area you name.
CodeWalk is a player only — it does not generate walks for you. Write the file however you like: by hand, with an AI, or with any tool — as long as it matches the format.
3. Start walking
Click the path icon in the Activity Bar, or run the CodeWalk: Open Walk command, then pick a walk to begin.
| Key | Action |
|---|---|
→ / ↓ |
Next step |
← / ↑ |
Previous step |
Home |
Reveal this step's code location |
Esc |
Back to walk list |
Keyboard shortcuts only work while the CodeWalk panel has focus — click anywhere in the panel to focus it.
- Step-by-step walkthrough — each step automatically opens the file, selects, and scrolls to the right line range. Focus stays on the panel, so your hands never leave the arrow keys
- Glossary terms — authors can annotate any step with terms; click to expand the explanation without cluttering the layout
- Six kinds of supporting content — tips, common misconceptions, todos, external references, code snippets, and diffs. Details in Six Kinds of Supporting Content below
- Syntax highlighting matches your theme — powered by Shiki, colors come straight from your current VS Code theme. Supports 23 languages — see Supported Languages below
- Quiz mode — take a quiz after finishing the walk to check whether you actually understood it. Every option explains why it's right or wrong, and a failing score suggests rereading the walk or retaking the quiz
- Staleness detection — a walk describes the code as it was at some point in time, and as the project keeps moving, it will eventually drift out of sync. CodeWalk checks each step: if the code merely shifted, it follows along automatically; if the content actually changed, it flags the step as stale and includes a one-click-copy way to regenerate the walk
- Resume where you left off — close and reopen VS Code, and the walk list still shows your last position
- Built for reading alongside an agent — select text in the panel to send it, with the step's context attached, to your editor's chat or your clipboard; walks can be opened by URI; and a read-only local MCP server lets an agent ask where you are. See Working with agents
CodeWalk assumes you're reading code with an AI agent nearby, and wires the two together in three directions.
Ask about what you're reading. Select any text in the panel — narration or code — and two buttons appear. One opens your editor's chat with a prompt already filled in, but not sent, so you can edit it first. The other copies the same prompt for a terminal agent. Either way the prompt carries your selection plus the current step's title, narration, and file:line, so you never have to re-explain where you are. If your editor has no chat command — older Cursor builds, for instance — it falls back to the clipboard.
Open a walk by URI. Whatever produced a walk can open it for you:
code --open-url "vscode://properworkstudio.codewalk-reader/open?walk=.codewalk/2026-01-30-auth-flow.codewalk.json&step=3"walk is repo-relative; step is an optional 0-based index. On Cursor, swap both halves: cursor --open-url and a cursor:// scheme. The panel opens even if it hasn't been opened yet this session.
Let an agent see where you are. With a workspace open, CodeWalk runs a local read-only MCP server and records its port in {tmpdir}/codewalk-mcp/{first 16 hex chars of sha256(workspace path)}.json. Point an agent at that port and it gets two tools:
| Tool | Returns |
|---|---|
codewalk_current_step |
The walk you're on, the step's index and title, its file and effective line range, and whether the anchor still matches |
codewalk_list_walks |
Every playable walk in the workspace, with paths and titles |
Both are read-only — an agent can see your position, not move it. If the same workspace is open in two windows, only one of them serves; the other says so rather than silently taking over.
A walk committed onto a PR branch hands the reviewer a guided path through the diff instead of a wall of changed files.
- Before opening the PR, generate a walk for the branch's diff — Authoring walks has a
git-diffscope for exactly this - Commit
.codewalk/<date>-<topic>.codewalk.jsononto the PR branch - Say so in the PR description: "walk through this with CodeWalk first"
- The reviewer checks out the branch, opens the panel, and arrow-keys through the change with your narration alongside it
Take your own quiz before you send it out: if you can't pass it, the change probably isn't ready for review. For the reviewer it stays optional — review is about going faster, and a mandatory quiz works against that.
Type definitions live in shared/schema.ts. Minimal example:
{
"title": "Example walk",
"ref": "<pinned commit sha>",
"steps": [
{
"title": "Entry point",
"file": "src/index.ts",
"startLine": 1,
"endLine": 1,
"narration": "This is where the program starts.",
"terms": [{ "term": "entry point", "explanation": "Where the program begins executing" }]
}
],
"quiz": [
{
"question": "...",
"options": ["A", "B"],
"correctIndex": 0,
"optionExplanations": ["Why A is wrong", "Why B is right"]
}
]
}| Field | Description |
|---|---|
ref |
The commit sha the walk was generated against |
steps[].anchor |
Optional but strongly recommended: the verbatim original code at those lines. Without it, staleness detection isn't possible — CodeWalk can only fall back to a rough comparison against ref |
quiz |
At least 1 question. Each can include optionExplanations, which must be the same length as options |
passThreshold |
Number of correct answers needed to pass. Defaults to a simple majority of the question count (e.g. 5 questions defaults to a pass threshold of 3) |
regenerateHint |
How to regenerate this walk. When staleness is detected, the panel shows a copy button for it |
steps[].items |
The step's array of supporting content items — see Six Kinds of Supporting Content below |
Each element of the steps[].items array is distinguished by its kind field, and a single step can freely mix multiple kinds:
| kind | Name | Description |
|---|---|---|
tip |
Tip | A block of supplementary text — useful for extra context or suggestions |
pitfall |
Common misconception | A "misconception" and "reality" pair that calls out a common misreading of the code |
todo |
Todo | Reminds the reader of a follow-up action, e.g. "remember to add a matching test" |
reference |
External reference | A label + URL linking out to external docs or resources |
snippet |
Code snippet | Quotes another piece of code (the file and line range can differ from the step's main range), with the same syntax highlighting and staleness detection |
diff |
Diff | Shows a before/after diff for a piece of code |
Syntax highlighting for snippet and diff is determined by file extension. Currently supported (23 languages):
- TypeScript
- JavaScript
- JSON
- Python
- Go
- Rust
- Java
- Kotlin
- Groovy
- Scala
- Dart
- Swift
- C#
- C
- C++
- PHP
- Ruby
- SQL
- CSS
- HTML
- Markdown
- Bash
- YAML
For extensions outside this list, CodeWalk shows the content as plain text rather than guessing a language.
Narration-style fields (like narration) accept a closed subset of markdown — to keep walks readable without ever letting formatting overshadow the code itself. Six syntax forms are supported:
- Inline code:
`code` - Bold:
**text** - Links:
[text](https://...)— only http/https take effect; other URLs are shown as literal text and aren't clickable - Unordered lists:
- item(nested indentation supported) - Ordered lists:
1. item - Level-2 subheadings:
## Heading(depth 2 only;#and below###aren't supported)
Anything else (tables, images, blockquotes, code blocks, headings other than #/### and below, raw HTML, etc.) is shown as literal plain text rather than breaking the walk. Short fields like titles, options, and term names only support the first three forms (inline code, bold, links) — lists and subheadings don't take effect there either.
Which fields belong to which tier is documented in the JSDoc for each field in shared/schema.ts.
The arrow keys, Home, and Esc inside the panel are handled by the webview itself, not VS Code keybindings — you won't find them in keybindings.json, and they don't need a when clause; they just work while the panel has focus.
The four commands below are real VS Code commands — searchable in the command palette and bindable to your own shortcuts:
| Command ID | Title | Purpose |
|---|---|---|
codewalk.openWalk |
CodeWalk: Open Walk | Open (or focus) the side panel |
codewalk.nextStep |
CodeWalk: Next Step | Advance one step, even without panel focus |
codewalk.prevStep |
CodeWalk: Previous Step | Go back one step, even without panel focus |
codewalk.revealCurrentStep |
CodeWalk: Reveal Current Step | Jump back to the current step's code location |
nextStep / prevStep exist for when you're mid-edit in the editor and want to move to the next step without moving focus back to the panel. Bind them to a shortcut and go.
In keybindings.json:
{ "key": "ctrl+alt+right", "command": "codewalk.nextStep" },
{ "key": "ctrl+alt+left", "command": "codewalk.prevStep" }CodeWalk currently has no settings (contributes.configuration is empty) — colors follow your editor theme, and everything else is driven by the walk file itself.
The panel says "No walks found"
Make sure the workspace root has a .codewalk/ directory, and that the files inside end in .codewalk.json.
A "line numbers may have drifted" warning appears
The current HEAD differs from the walk's pinned ref. If the walk includes anchor, CodeWalk falls back to a more accurate step-by-step comparison instead, and this warning won't appear.
A step is marked "no longer matches the current code" That code genuinely changed. The panel shows the content as it was when generated so you can compare, with a button to open the current file. When this happens, regenerate the walk rather than manually fixing line numbers — a walk is meant to be disposable; let it be regenerated to match the latest code instead of patching it by hand.
A snippet has no syntax highlighting The file's extension isn't among the 23 supported languages.
pnpm install
pnpm watch # compile in watch mode
pnpm test # Vitest unit tests
pnpm typecheck # tsc --noEmit
pnpm format # Prettier, whole project
pnpm package # bundle into codewalk.vsixPress F5 in VS Code to launch the Extension Development Host for debugging.
Installing the VSIX locally:
pnpm package
code --install-extension codewalk.vsixCodeWalk is currently maintained by one person, not a commercial product.
Reporting issues — issues are welcome. I'll do my best to address them, but can't promise a response time.
Contributing — please open an issue to discuss direction before sending a PR. This repo manages its behavior spec with OpenSpec; changes that haven't been discussed first are likely to conflict with the existing spec and be hard to merge.
Support — if CodeWalk saved you some time, you can buy me a coffee. Entirely optional, and it doesn't buy priority support — the note above still applies.