CodeWalk — interactive code walkthroughs for VS Code

Product-tour style, step-by-step walkthroughs of a codebase, shown inline on the code: the editor jumps to the right file, spotlights the lines, dims everything else, and a bubble explains the step with Back / Next / Finish buttons.

Walkthroughs can be:

• Generated by Claude Code from a file, a selection, a folder, the whole repo, or a git diff (great for PR reviews and onboarding).
• Recorded by hand: select lines → ⌘⌥R → write a note.
• Shared: tours are plain JSON in .codewalk/, so commit them, import them from a URL, or export them as Markdown.

Try it

cd codewalk
npm install
npm run compile

Open the folder in VS Code and press F5. In the Extension Development Host window, open the CodeWalk icon in the activity bar and start "How CodeWalk works" — a walkthrough of this very extension.

To install it for real: npm run package and then Extensions → … → Install from VSIX.

Generating with Claude Code

Requires the Claude Code CLI (claude) on your machine and signed in.

1. Right-click a file/folder in the Explorer (or run CodeWalk: Generate Walkthrough with Claude Code…).
2. Pick the scope and, optionally, say what to focus on and who it is for.
3. Claude reads the code with read-only tools (Read, Glob, Grep, LS), writes the tour, and it opens in the sidebar.

CodeWalk: Generate Walkthrough from Git Diff… explains uncommitted changes, the last commit, your branch vs main, or any custom ref range — step by step, on the current file contents.

Settings (codewalk.*): claudePath, claudeModel, claudeExtraArgs, detailLevel (overview / detailed / exhaustive), toursDirectory, highlightColor, dimOtherCode.

Playing

Editing a tour's JSON while it is playing hot-reloads the current step.

Tour format

{
  "title": "How authentication works",
  "description": "From the login route to the session cookie.",
  "steps": [
    {
      "title": "The login route",
      "file": "src/routes/auth.ts",   // relative to the repo root
      "line": 12,                      // 1-based, inclusive
      "endLine": 30,
      "body": "Markdown explanation…",
      "anchor": "router.post('/login', async (req, res) => {"  // optional; lets the step survive edits
    }
  ]
}

If a file has changed since the tour was written, CodeWalk searches ±200 lines for the anchor text and moves the highlight accordingly.

How it's built

• Bubble: VS Code's Comments API (createCommentController) — the only sanctioned way to put a rich, inline, Markdown card on a line. Buttons come from the comments/commentThread/title menu plus command links in the body.
• Spotlight: two TextEditorDecorationTypes — a highlight for the step's lines and an opacity decoration for the rest of the file.
• Generation: claude -p <prompt> --output-format json --allowedTools Read,Glob,Grep,LS, run with the workspace as cwd; the JSON block in the answer is validated, steps pointing at missing files are dropped, anchors are captured, and the tour is written to .codewalk/.