Sefism is free for learners. We are here to help you grow, one step at a time.Join for free
Sefism.
Other

VS Code Extension for Codebase Onboarding Maps and Guided Tours

A VS Code extension that helps new developers and interns understand an unfamiliar codebase: it maps modules and dependencies, highlights entry points and busy files, and lets seniors record guided tours that warn when the code they point at changes. A developer tools final year project with a measured onboarding study.

Topics
Difficulty

Intermediate

A small team, or one strong student willing to learn something new.
Effort

2 semesters · 2 to 3 students

Deliverables

7 to ship

3 optional extras

Suggested stack

TypeScriptVS Code Extension APITree-sitter parsersWebview with D3 or Cytoscape.jsGit log parsingVitest
A suggestion, not a requirement. Swap anything for what you already know.

What you should ship

  • A VS Code extension that parses a repository in at least two languages with Tree-sitter and builds a module and import graph shown in an interactive side panel.
  • Automatic detection of entry points (main files, route definitions, CLI commands) and a "start here" list for newcomers.
  • A file heat layer based on Git history: recent churn, number of authors and last change date, shown in the graph and the file explorer.
  • Guided tours stored as a JSON file in the repository, recorded by clicking through code, with notes per step.
  • Tour drift detection: when code referenced by a tour step moves or changes, the step is re-anchored by content or flagged as stale.
  • A command that exports the module map as a Mermaid diagram for the README.
  • An onboarding study with at least eight participants comparing time to complete first tasks with and without the extension.

If you have time left

  • A CI check that fails a pull request when it makes a tour step stale without updating the tour.
  • Import existing CodeTour files and add drift detection to them.
  • Support for a third language and for monorepos with multiple packages.

The problem new developers face in an unfamiliar codebase

An intern joins a software house, a student joins an open source project, or a developer inherits a client's app. They open a repository with hundreds of files and no map. Where does a request start? Which folders matter? Which files change every week and which have not been touched in years? Seniors explain it once in a meeting, the explanation is forgotten, and the next newcomer asks the same questions. Any written onboarding document goes stale the week after it is written, because code moves and documents do not.

Reading large codebases is one of the skills graduates say they were never taught, and one that teams quietly spend a lot of senior time on.

What already exists and the gap

  • CodeTour from Microsoft lets people record and replay guided walkthroughs in VS Code, anchored to file and line; tours can silently point at the wrong line once code changes.
  • Sourcegraph offers code search and navigation across large codebases, aimed at organisations.
  • CodeScene analyses Git history to find hotspots and knowledge risks, as a commercial platform.
  • GitHub code navigation gives go-to-definition in the browser, but no overview or onboarding path.

The gap is one tool, inside the editor people already use, that combines a structural map, history-based signals and guided tours that notice when they have gone stale.

What you build

An extension with three panels and one file format.

  • Map: Tree-sitter parses source files and extracts imports, exports and top-level definitions. The extension builds a module graph, collapses folders into clusters, and draws it in a webview. Clicking a node opens the file.
  • Signals: from git log, compute churn, author count and age per file. Entry points are detected with simple, per-language rules (a main function, framework route files, package.json scripts).
  • Tours: a senior clicks "record tour", walks through the code, writes a note per step and saves. Tours live in the repository and are reviewed like code.
  • Drift: each tour step stores the file, line and a small fingerprint of the surrounding code. When the file changes, the extension searches for the fingerprint and re-anchors, or marks the step stale if it cannot.

The technically interesting part

Drift detection is the core problem. Line numbers break as soon as someone adds an import. A good approach combines the enclosing symbol (function or class name from the syntax tree) with a fuzzy match on the surrounding lines, similar in spirit to how diff and patch tools find context. You must decide when a match is confident enough to move silently and when to ask a human. Build a test set from real repository history: take tours written against an old commit, replay the Git history, and measure how often steps re-anchor correctly, wrongly or get flagged.

The second challenge is keeping the extension fast on large repositories: parse incrementally, cache results per commit, and never block the editor.

How to evaluate it

  • Drift accuracy: on at least three open source repositories and 100 or more tour steps replayed across six months of history, report correct re-anchor, wrong re-anchor and flagged rates.
  • Performance: time to build the map for repositories of 1,000, 10,000 and 50,000 files; extension memory use.
  • Onboarding study: eight or more students or junior developers each do two small tasks in an unfamiliar repository, half with the extension; compare time to first correct change and a short confidence survey.
  • Adoption: publish to the marketplace and report installs and any issues filed during the project.

Suggested plan

  1. Weeks 1 to 3: interview three or four developers about their last onboarding; pick languages and test repositories.
  2. Weeks 4 to 8: Tree-sitter parsing, module graph, map webview.
  3. Weeks 9 to 12: Git signals and entry point detection.
  4. Semester 2, weeks 1 to 5: tour recording, storage and playback.
  5. Weeks 6 to 9: drift detection and the replay test harness.
  6. Weeks 10 to 14: onboarding study, marketplace release and report.

Path to a product

Release the extension free and open source to build users, then sell a team plan: shared tours across repositories, a CI check for stale tours and onboarding analytics for engineering managers. The first paying customer is a software house or agency that onboards interns every few months and rotates developers across client projects. Price per seat per month, with free use for open source projects and universities.

Scope warning

Do not build a chat assistant that explains code; it hides whether your map and tours work. Do not support every language; two done well is enough. Do not build a separate web platform before the extension itself is useful.

Learn what you need on Sefism

Get help with this idea

Tooling projects are judged on whether real people use them, so recruit your study participants early. If you want a second opinion on scope, stack or how to evaluate it before you pitch it to your supervisor, bring your draft proposal and we will pressure-test it together. You build it; the guidance is on the decisions.

New here? Create a free account first.

Ideas and guidance, not finished projects

These are project ideas and scoping guidance, published free for students to use as a starting point. I do not build, write, or sell final-year projects, and I do not complete coursework for anyone. Take an idea, make it yours, and build it.

Not sure this one fits you?

I help students pick an idea that matches their skills and their deadline, then scope it down until it is finishable. Guidance only, never done for you.

Discuss this idea
Work with me

Stuck on something specific?

Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.

Book a free sessionSee all services

Follow along

New writing, resources and project ideas land here first.