tutor

A Claude Code plugin that turns an unfamiliar codebase into an interactive onboarding course. It reviews a repo, generates layered documentation capturing the concepts, data flows, use cases, and gotchas that aren't in the README or obvious from the code — then walks you through them and quizzes you, always driving you back to the real source.

Unlike a one-off "explain this repo" prompt, tutor produces durable, evidence-cited docs that live in the repo, tracks what you've studied, and tests your understanding over time.

The plugin, repository, and marketplace entry are all named tutor.

Why

Reading generated prose about a codebase feels productive but rarely sticks — you end up trusting a summary instead of understanding the code. tutor is built around one rule: every claim cites a real file:line, and you don't get credit for an answer until you've opened the code. The docs are a map; the territory is still the source.

Installation

Add the marketplace and install the plugin from within Claude Code:

/plugin marketplace add patmagee/tutor
/plugin install tutor@tutor

Once installed, the three commands below are available in any repo you open.

The workflow

/tutor:build-study-guide   →   /tutor:study   →   /tutor:quiz
      (generate)                  (learn)             (test)

1. Build the onboarding docs once for a repo.
2. Study them as a guided walk — pick a mode and a starting point.
3. Quiz yourself to confirm what stuck; review again where it didn't.

You can re-run review and quiz as often as you like; build is occasional (and supports incremental --refresh when the code drifts).

Commands

/tutor:build-study-guide — generate the docs

Reads the actual source, then writes a structured doc set under docs/onboarding/: an architecture overview, one doc per layer, a cross-cutting gotchas file, and the "how to build" / "how to run and debug" docs that are usually missing or stale.

It auto-detects how to decompose the repo (by service, component, feature, or layer), proposes a layer breakdown for you to confirm, and asks which perspective to emphasize. Every claim it writes is backed by a file:line citation, and it lints its own output before finishing.

/tutor:build-study-guide [path]
                         [--perspective structure|data-flow|security|use-cases|gotchas|comprehensive]
                         [--axis service|component|feature|layer]
                         [--refresh]

Argument	Default	Notes
path	current directory	Repo root to analyze.
--perspective	comprehensive	Lens to emphasize.
--axis	auto-detected	Force the decomposition axis instead of detecting it.
--refresh	off	Regenerate only the docs whose source changed since the last build, rather than rebuilding everything.

/tutor:study — learn it, guided

Walks you through the generated docs one layer at a time, in one of three study modes. It tracks coverage per topic, so you can stop any time and pick up where you left off.

/tutor:study [layer-id]
             [--route data-flow|top-down|bottom-up]
             [--mode guided|lecture|reference]

Study modes — think elementary-school vs. university textbook:

Mode	Pace	Code	Questions
guided (default)	one topic at a time	points you to file:line, never quotes it	asks a question you can only answer by reading the code, before explaining
lecture	a whole layer at once	narrates and quotes the relevant code inline	optional comprehension check after the layer
reference	a whole layer at once	narrates and quotes the relevant code inline	none — read straight through

guided is the "drive-to-code" experience: it won't narrate the answer until you've looked. lecture and reference are textbook-style reading for when you want to absorb a dense layer quickly — the code is shown inline, with citations still clickable so you can dive in.

If you don't pass --mode, review asks which one you want at the start. You can also switch modes mid-session ("switch to reference").

Routes decide the order layers are visited:

• --route top-down — the order they appear in the index (default ordering).
• --route bottom-up — reverse order.
• --route data-flow — follow the end-to-end data path described in the overview.

Resume & coverage. Review records each topic you walk in .tutor/review.md. The next time you run /tutor:study without arguments, it shows how much you've covered and offers to resume at the first topic you haven't walked yet — or you can pick a different layer to study instead.

When you finish a layer, review offers to launch /tutor:quiz for that layer so you can test yourself immediately.