CodeTour CLI

Algorithmic maintenance of CodeTour files: keep .tour walkthroughs accurate as the code they narrate evolves.

Unofficial companion tool. codetour-cli is an independent, unofficial companion to CodeTour, the VS Code extension by Jonathan Carter (Microsoft). It is not affiliated with, endorsed by, or maintained by Microsoft or the CodeTour project. It exists to serve CodeTour and its users — keeping .tour files accurate as the code they walk through evolves.

The problem

A CodeTour step pinned to src/auth.py:42 is correct the day it's written. Twenty commits later, line 42 is something else entirely — and every tour in the repository is silently lying. Tours are the best onboarding artifact a codebase can have, if someone keeps them true. Nobody keeps them true by hand.

codetour-cli tracks each step across the commits between a tour's pinned ref and HEAD (git hunk mapping plus content heuristics), applies high-confidence line updates automatically with byte-preserving surgical edits (your diff shows the step change, not a rewritten file — via json-source-edit), and routes everything it isn't sure about to a review report designed to be worked by humans and AI agents alike.

Install

pip install codetour-cli        # Python ≥ 3.10

Quickstart

codetour-cli status                  # which tours lag HEAD?
codetour-cli migrate --dry-run       # preview: what would move, what needs review
codetour-cli migrate                 # apply confident updates; write review report
codetour-cli lint                    # ground-truth check tours against the workspace

The maintenance loop

author tour ──► lint ──► commit, pin `ref`
     ▲                        │
     │               ...code evolves...
     │                        │
     │                   status  (tour lags HEAD?)
     │                        │
apply-review ◄── review report ◄── migrate [--dry-run]
(checked steps            (auto-applies confident updates;
 written back)             low-confidence → the report)

Steps the migration can't confidently place land in MIGRATION-REVIEW-{tour}-{commit}.md: each entry carries the step's original description (its intent), old → new location, why confidence dropped, and the actual code now at the proposed location. Check the boxes you approve — or correct the locations inline — then:

codetour-cli apply-review MIGRATION-REVIEW-mytour-abc12345.md

The report is deliberately dual-audience: an AI agent can read it, judge each proposed location against the step's stated intent, mark the checkboxes, and apply — the same workflow, no human bottleneck for the easy calls. (A companion Claude skill teaches agents both tour authoring and this maintenance loop.)

Commands

Flags worth knowing (migrate): --threshold X — the auto-apply confidence bar (note: confidence takes 5 exact values, not a smooth dial; see docs/adr/0016-*.md); --clean-reviews — drop stale review reports from earlier target commits; --context-lines N — code context in reports (default 7, config review.context_lines). (apply-review): --auto-approve-above X — also apply unchecked steps at or above that confidence; steps marked for deletion are never auto-approved.

MCP server

For agents on MCP-capable surfaces, the same operations are exposed as structured tools:

pip install "codetour-cli[mcp]"
codetour-mcp                       # stdio MCP server

Five tools — tour_status, lint_tours, migrate_tour (defaults to dry-run; a model-facing tool must not mutate by default), read_review_report, apply_review — each a thin wrapper calling the exact functions the CLI verbs call, with identical semantics (including: deletion-marked steps are never auto-approved). Register it e.g. in .mcp.json:

{ "mcpServers": { "codetour": { "command": "codetour-mcp" } } }

Design record

This tool is developed with the ADRs4AI methodology — every architectural decision, including the ones that were later reversed, lives in docs/adr/ as a first-class deliberation record: the byte-preserving editing contract, the confidence quantization study, the review-workflow design, and the retirement of ideas that eight months of shipped reality outvoted.

License

MIT — like CodeTour itself.