Annotate
Code walkthrough builder for devrels, educators, and engineers
CodeTour
Record and replay guided walkthroughs of your codebase
Visual Studio Code extension that lets you create interactive, step-by-step tours through code. Perfect for onboarding, bug reports, and code reviews.
Overview
Accelerate Developer Onboarding with Interactive Code Tours
CodeTour is a Visual Studio Code extension that transforms how teams share knowledge about their codebases. Instead of static documentation or lengthy README files, you can record interactive walkthroughs that guide developers through specific features, bug fixes, or architectural patterns step-by-step.
How It Works
Each tour consists of a series of steps anchored to specific files, directories, or lines of code. As developers navigate through a tour, they see contextual descriptions (with full Markdown support) that explain what the code does and why it matters. Tours can highlight specific code selections, span multiple files, and even work across multi-root workspaces.
Flexible Sharing and Deployment
Tours can be checked directly into your repository as .tour files, making them available to every contributor who clones the project. Alternatively, export tours as standalone files that anyone can replay without needing to clone the entire codebase—ideal for code reviews, PR walkthroughs, or remote collaboration. Whether you're onboarding new team members, documenting complex features, or providing context for bug reports, CodeTour makes tribal knowledge accessible and actionable.
Highlights
Interactive step-by-step code walkthroughs with Markdown-formatted descriptions
Anchor tour steps to specific files, lines, directories, or code selections
Check tours into repositories or export as standalone shareable files
Link multiple tours in sequence for comprehensive learning paths
Pros
- Dramatically reduces onboarding time by providing contextual, in-editor guidance
- Tours live alongside code, making documentation easier to maintain and discover
- Supports multi-root workspaces and cross-file navigation for complex codebases
- Exported tours enable code review and collaboration without repository access
Considerations
- Requires Visual Studio Code; not available for other editors or IDEs
- Tours can become outdated if code changes significantly without tour updates
- Limited to text-based explanations; no support for video or audio annotations
- Effectiveness depends on tour authors creating clear, well-structured content
Managed products teams compare with
When teams consider CodeTour, these hosted platforms usually appear on the same shortlist.
Looking for a hosted option? These are the services engineering teams benchmark against before choosing open source.
Fit guide
Great for
- Teams onboarding new developers to large or complex codebases
- Open-source projects wanting to lower contribution barriers
- Documenting bug reproduction steps or specific feature implementations
- Code reviewers explaining PR changes or architectural decisions
Not ideal when
- Teams not using Visual Studio Code as their primary editor
- Projects with rapidly changing codebases that make tour maintenance difficult
- Organizations requiring video-based training or multimedia documentation
- Solo developers who don't need to share knowledge with others
How teams use it
New Developer Onboarding
Junior engineers navigate a primary tour on day one, understanding project structure and key patterns without waiting for senior developer availability.
Bug Report Documentation
QA team creates a tour showing exact reproduction steps through the codebase, enabling developers to quickly locate and fix the issue.
Pull Request Context
Author exports a tour explaining their PR changes across multiple files, helping reviewers understand the rationale and implementation approach.
Feature Area Deep Dive
Tech lead records a linked series of tours covering authentication flow, allowing team members to self-serve when working on related features.
Tech snapshot
TypeScript99%
JavaScript1%
Frequently asked questions
Do tour participants need to install the CodeTour extension?
Yes, anyone playing back a tour needs the CodeTour extension installed in Visual Studio Code. However, exported tour files can be shared and replayed without cloning the repository.
Can I edit a tour after recording it?
Absolutely. Right-click any tour in the CodeTour tree view and select 'Edit Tour' to add, delete, reorder, or modify steps. You can also change the tour title, description, or git reference.
How do I keep tours up-to-date as code changes?
Tours are stored as JSON files in your repository. Treat them like documentation—review and update them during code reviews or when refactoring areas they cover. The extension provides editing tools to quickly adjust steps.
Can tours span multiple files or folders?
Yes. Tours can include steps across any files in your workspace, including multi-root workspaces. You can also create directory steps or content steps for introductory explanations not tied to specific code.
What's the difference between checking in tours versus exporting them?
Checked-in tours are committed to your repository as .tour files, making them available to all contributors. Exported tours are standalone files you can share via email or chat for one-off walkthroughs without repository access.
Project at a glance
Active- Stars
- 4,498
- Watchers
- 4,498
- Forks
- 135
LicenseMIT
Repo age5 years old
Last commit3 weeks ago
Primary languageTypeScript
Last synced 2 hours ago