CodeWalk

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.

Quick Start

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.

Keyboard shortcuts only work while the CodeWalk panel has focus — click anywhere in the panel to focus it.

Features

• 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

.codewalk.json format

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"]
    }
  ]
}

Key fields

Six kinds of supporting content

Each element of the steps[].items array is distinguished by its kind field, and a single step can freely mix multiple kinds:

Supported languages

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.

Markdown support

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.

Commands and shortcuts

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:

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.

FAQ

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.

Development

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.vsix

Press F5 in VS Code to launch the Extension Development Host for debugging.

Installing the VSIX locally:

pnpm package
code --install-extension codewalk.vsix

About this project

CodeWalk 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.

License

MIT