CodeTour: recorded code walkthroughs inside VS Code

The onboarding gap CodeTour targets

A new contributor clones a repository and faces a directory tree with no narrative. The usual answers are a CONTRIBUTING.md file, a wiki page, or asking someone. CodeTour's README frames the problem that way: the extension lets developers clone a repo and "immediately start learning it", without referring to a CONTRIBUTING.md or relying on help from others. A tour is a series of interactive steps, each attached to a directory, a file, or a file and line, with a markdown description of the code at that point. The audience is narrow and specific: teams already working in VS Code who onboard people into large or unfamiliar areas, and maintainers who want to attach context to a pull request change. The README also names bug reports and code review as use cases, which is a broader pitch than onboarding alone. Whether a recorded tour survives a month of commits is a separate question, and the answer depends on a recorder setting described below.

How a tour is stored and replayed

Tours are written as files into the workspace, which is why the README explains that recording inside a multi-root workspace prompts you to pick the destination folder. The repository keeps its own tours in a .tours/ directory at the top level, and the extension contributes a codetour.customTourDirectory setting for pointing that location elsewhere. The package.json declares two entry points, ./dist/extension-node.js for the desktop extension host and ./dist/extension-web.js for the web build, and activation events of onStartupFinished and onNotebookEditor:codetour, so the extension loads when VS Code finishes starting and when a CodeTour notebook editor opens. That notebook activation event is the detail most descriptions miss: a tour can be presented through VS Code's notebook UI rather than only as inline comments. The README's exporting section describes a second path where a tour is exported to a "tour file" so someone can replay it without cloning the code, which is how a tour becomes a shareable artifact rather than a repo-local one. The schema.json file at the repository root is the contract for that format.

Recording a first tour step by step

Installation is the standard VS Code route. The README links the extension through aka.ms/codetour, and the package.json lists the publisher as vsls-contrib with the display name CodeTour. There is no npm package to install and no CLI. Once the extension is present, the README says to click the + button in the CodeTour tree view or run the CodeTour: Record Tour command. During recording you open a file, click the comment bar on the line you want to annotate, and write a markdown description. The tree view shows the tour being recorded with a microphone icon next to its name. Stopping the recorder is the red square action. If you want the tour to start automatically when someone opens the workspace, the codetour.promptForWorkspaceTours setting controls the notification shown the first time a workspace with tours is opened, and it defaults to true. The README does not document a rollback for a recording session, so treat the stop action as the commit point for the steps you have added.

Line numbers versus patterns, the setting that decides your maintenance bill

The recorder has a mode setting that most writeups skip. codetour.recordMode accepts lineNumber or pattern and defaults to lineNumber. In the default mode a step is anchored to the line where you created the comment. That is precise at record time and brittle afterwards: inserting a function above an annotated line shifts every step below it. The pattern mode exists for that reason, and the README does not explain in the excerpt how a pattern is derived or what happens when a pattern matches more than one location. The practical consequence is that a tour over a file with heavy churn will need editing, and the extension gives you the tools for that: steps can be moved up and down from the tree view, the step menu, or the comment UI, and they can be deleted individually or in multi-select with Cmd+click on macOS or Ctrl+click on Windows and Linux. There is also a codetour.showMarkers setting, default true, that controls whether tour markers appear in the editor gutter. None of this is automatic repair. Someone still has to notice the drift.

Where CodeTour stops being the right tool

The extension is workspace-scoped. The package.json sets extensionKind to workspace, meaning the extension runs where the code is, which matters for remote and web scenarios but also means the tour experience is tied to the editor that has the extension installed. A reviewer who works in a JetBrains IDE gets nothing from a .tour file except a JSON document; the README describes no export to a format those editors consume. The second boundary is the release cadence. The most recent release listed is v0.0.59 from 2023-03-24, while the last push to the repository was on 2026-05-05, so the code has moved since the published extension version. Anyone pinning behaviour to the marketplace build is pinning to a version that is three years old. The third boundary is scope: a tour is a sequence of pointers with prose. If what you actually need is generated API documentation or an architecture diagram that stays current, a recorded sequence of line anchors is the wrong artifact. The README's own overview.drawio.svg in the repository root is a reminder that some explanations are better drawn once than recorded step by step.

CodeTour against a plain markdown walkthrough

The obvious alternative is a WALKTHROUGH.md file with headings and line references, which costs nothing, needs no extension, and renders anywhere. The difference in approach is real: a markdown file is passive prose that a reader maps onto the code themselves, while a CodeTour file is a sequence of steps the editor can drive, opening the right file and highlighting the right span as the reader advances. That matters when the explanation depends on the reader being in the code at the moment they read the sentence. It matters much less when the explanation is conceptual and does not need a cursor. The cost side is equally clear: markdown survives refactors because it names symbols and concepts, and line-anchored tour steps do not. A team that already maintains good documentation should ask whether the missing piece is really interactivity, or just a document nobody has written. The README positions tours as complementary to CONTRIBUTING.md rather than a replacement, and that framing is honest.

Licence, maintenance and the cost of keeping tours alive

The repository is licensed MIT, with LICENSE.txt at the root, so the code can be reused and modified under those terms; this is a statement about the licence file, not legal advice, and anyone redistributing a modified build should read the licence text themselves. The maintenance picture is mixed and worth stating plainly. The repository is not archived, and the last push was on 2026-05-05, so work has happened recently. The published releases tell a different story: v0.0.59 landed on 2023-03-24, after v0.0.58 and v0.0.57 both on 2021-07-08. Anyone depending on the marketplace extension is depending on the 2023 build. Upgrading means either waiting for a release or building from source, and the repository ships a webpack.config.js and a package-lock.json, so a local build is possible but the README does not document one in the excerpt provided. The ongoing cost is editorial rather than technical: every tour is a document that ages, and the extension provides editing tools but no drift detection. Budget for someone owning the .tours/ directory the way they would own a docs folder.

Editorial conclusion

Adopt CodeTour if your team lives in VS Code and you want onboarding or PR context stored as reviewable .tour files next to the code. Skip it if your reviewers work in JetBrains IDEs, or if the code churns enough that line-anchored steps would need constant repair. Before rolling it out, open one .tour file and confirm whether its steps carry a pattern or only line numbers, since that decides how much maintenance the tour will cost you.

Frequently asked questions

Official sources

1. License: MIT
2. microsoft/codetour on GitHub
3. Project website
4. README
5. Releases