git-tour

One command turns any repo into a guided onboarding tour that plays inside VS Code — via Microsoft's official CodeTour extension. Nothing to replace, nothing for your teammates to install.

npx git-tour

That's it — auth is automatic: git-tour uses your ANTHROPIC_API_KEY if one is set, and otherwise (or if the key fails) falls back to your installed Claude Code login, covered by a Claude Pro/Max subscription. Open the repo in VS Code and a 10–15 step tour starts from the CODETOUR panel: entry point → main flow → core abstractions → config → tests → where to make your first change.

Why

Joining a codebase means days of reading scattered files in the wrong order. Microsoft's CodeTour solved the playback problem years ago — guided, step-by-step walkthroughs at real file/line positions in your editor. But tours had to be hand-authored, so almost nobody wrote them.

git-tour does the authoring. It scans the repo, has Claude write the tour a senior engineer would give you on day one, verifies every file and line reference against the actual code, and writes a standard .tours/getting-started.tour file you can commit. Teammates who clone the repo get the tour for free.

How it compares

| | git-tour | Understand Anything | Hand-written CodeTours | |---|---|---|---| | Setup | npx git-tour | Install plugin + multi-agent pipeline | Author every step yourself | | Time to first tour | ~1 minute | Minutes to much longer on large repos | Hours | | Cost per run | ~$0.10–0.50 | "Significant tokens" (their words) | Free but nobody does it | | Where the tour plays | Your editor, at real file/line positions | Their web dashboard | Your editor | | Teammates need | Official CodeTour extension only | The plugin + a run or committed graph | Official CodeTour extension only | | Best for | A 2-minute orientation, today | Deep platform adoption, knowledge graphs | Tours needing human nuance |

Understand Anything is excellent at what it does — this is the 80/20 version for people who want a tour, not a platform.

How it works

scan            →  analyze                →  verify & emit
repo walk +        Claude writes the         every anchor located in the
importance         tour, anchored by         real file; unverifiable steps
ranking            verbatim snippets         dropped; .tour JSON written

The verification step is the point: LLMs hallucinate line numbers, so git-tour never trusts them. The model returns verbatim code snippets; we locate each one in the actual file and derive the real line. A step that can't be verified is dropped rather than shipped broken.

Usage

npx git-tour [path]           # generate .tours/getting-started.tour
npx git-tour --dry-run        # preview in the terminal, write nothing
npx git-tour --claude-code    # no API key: use your Claude Pro/Max subscription via Claude Code
npx git-tour --model claude-sonnet-5
npx git-tour refresh          # fix drifted line numbers after code changes — free, instant
npx git-tour refresh --check  # CI mode: fail the build if the tour went stale

Tours that never go stale

The reason nobody writes code tours by hand isn't just the authoring effort — it's that tours rot. Code moves, line numbers drift, and a tour written last month points at the wrong lines today.

git-tour fixes this at the data layer. Every step carries its anchor — the verbatim code snippet it points at — inside the .tour file (an extension field CodeTour safely ignores). git-tour refresh re-locates every anchor and rewrites drifted line numbers in milliseconds, with no LLM call and no cost. Steps whose code was truly deleted are reported for regeneration instead of silently pointing at the wrong line.

Run it as a pre-commit hook or in CI with --check, and your tour stays correct forever.

Requires Node 20+ and either an Anthropic API key (~$0.10–0.50 per run, printed after each run) or a Claude Pro/Max subscription with Claude Code installed — then --claude-code needs no key and no credits.

Roadmap

• Task-scoped tours — git-tour "how does authentication work?" generates a tour through just that slice
• Catch-up tours — git-tour --since 3-weeks tours what changed while you were away
• CI mode: regenerate the tour on merge to main
• More LLM providers

Star the repo if you want these — it's how I prioritize.

License

MIT