Render a session — or any subject — as explorable HTML.
walkthrough turns "what did we just do" into a self-contained interactive page — prose, architecture diagrams, decision records, and a file/timeline view — instead of a scroll back through the transcript. It works from two kinds of input: a session or a subject (a plugin, the marketplace, any path). Both render to the same house style.
claude plugin install walkthrough@apurvbazari-pluginsThat's it. No setup step, no configuration file required.
A composed document, not a transcript dump
Open the file in any browser and you get a synthesized document — a summary and type tags for the session, flow diagrams, system maps for anything with parts and connections (§ System maps), decision records (what was chosen, what was rejected, why), a file-touch list with real path:line references, and a timeline and metrics where the session has them.
For richer surfaces there are two interactive components: an interactive explorer — a selector that drives a live diagram region and a detail pane from one shared data model, useful for multi-component architectures where you want to navigate relationships rather than read a static diagram — and a data-driven step timeline — phases of parallel and sequential steps with source pills and micro-cycles, useful when the session covers a pipeline, workflow, or multi-phase build.
Underneath sits a concept-coverage layer: a concept-fidelity gate that routes each concept to the renderer best-shaped for it, across concept-shaped renderers including a decision tree, a recursive tree, a layer stack, a layered ERD, and a causal hypothesis ladder — so branching logic, hierarchies, layered stacks, data models, and debugging traces each render in the shape that fits them.
Components adapt to the session — the catalog is a floor, not a ceiling. When content fits no off-the-shelf component, a bespoke one is composed from the same design-system primitives so it still looks native, and empty sections are omitted rather than stubbed. After writing the file, create surfaces a short coverage summary — what made it into the document and what was intentionally omitted — so you can spot anything left out before you close the session.
No setup, no config
Install and run. There is no setup step and no configuration file required — /walkthrough:create [focus] produces a readable artifact of the session whenever you want one: after a debugging marathon, at the end of a feature, before a handoff, or to share with someone who wasn't in the room. With no argument it covers the whole session.
Two inputs, one visual layer
Everything walkthrough renders comes from one of two input modes. A session drives create and update; a subject drives document. The two lanes converge on the same shared renderer and emit one portable HTML file. Click a lane for detail.
The visual layer is reused verbatim across all three skills — one house style, two themes, an open component system, everything inlined. Only the model and the gathering differ: document swaps in its own subject model where create uses the session model. That shared layer is why a session recap and a plugin docs page are recognizably the same artifact.
The model-before-markup pipeline
create runs a fixed five-stage pipeline: the full structured model is built before a single HTML tag is written, and two quality gates bracket the render. This page was produced by /walkthrough:document running this same flow over the plugin's README and manifest. Click any step for detail.
create runs this flow over a session: gather reads cited source files so path:line refs are real, synthesize builds the session model, select maps it to components via the concept-fidelity gate, assemble inlines the scaffold, and write emits the file. Rendering never starts from the raw transcript — the full model is built first. document runs the same flow over a subject instead; update adds two stages in front — reconstruct the prior model from the rendered HTML and merge in explicitly-named files — before re-entering it.
Rich detail surfaces
Click a node, card, or cross-link and its detail opens. Light detail opens in a structured glance pane; richer content — a hosted diagram, code — opens in a centered sheet that can itself open further detail, nested. Click a surface for detail.
The pane is the lightweight right-edge glance; the sheet is a centered surface roomy enough to host a full diagram or code block. A surface can itself open another — so a node opens a sheet, and a cross-link inside that sheet opens the next detail — letting you navigate relationships in a multi-component architecture rather than read one static diagram. Empty fields are omitted rather than stubbed, so each surface shows only what it actually has.
The shared openSurface(id) router uses a SURF map to decide whether to open the pane or push a native <dialog> sheet. Sheets stack in the browser top layer via showModal() — free focus-trap, top-down Escape, and a token ::backdrop blur — capped at three levels of nesting.
Concept coverage — the right renderer for every concept
The concept-coverage layer ensures each kind of idea renders in the shape that fits it. Synthesis classifies each concept it wants to convey into a type at selection time, and the concept-fidelity gate routes it to the registered renderer — or, for an uncovered type, to a logged bespoke component. The gate never force-fits a concept into a component not registered for its type.
The built-in map currently covers 30 concept-types with zero uncovered rows. Services, stores, queues or modules connected free-form (nonlinear-system), a module dependency graph (module-dependency) and one system's structure before and after a change (structure-change) all render as a system map. A selection of the concept-shaped renderers is below — click any renderer name for detail.
| Concept-type | Trigger | Renderer |
|---|---|---|
| branching-logic | Labeled yes/no/condition edges, a tree with no cycles | decision tree |
| hierarchy | Strict one-parent containment, n levels deep | recursive tree |
| layering | Ordered vertical bands, each touching only neighbors | layer stack |
| data-model | Entities with field lists; FK edges carry cardinality (1:N, N:M) | layered ERD |
| causal-chain | Symptom → causes ruled in/out by evidence → root cause | causal hypothesis ladder |
| nonlinear-system | Services, stores, queues or modules connected free-form; may nest in boundaries; may cycle | system map |
The concept-coverage map (concept-coverage.md) is the single source of truth for which concept-types are covered and which renderer each routes to. Disambiguation rules handle close neighbors: for instance, guards and transitions between states route to a state machine, not a decision tree, while a cycle between components (services, stores, queues, modules) stays a system map; a data model is carved out too, because an ERD renders its own cycles by breaking and marking them rather than handing them to a state diagram; strict one-parent containment routes to the recursive tree, while import edges with shared leaves are a module dependency graph and route to the system map. An uncovered concept-type gets a bespoke component and a new ⚠️ row in the map — the hole stays visible rather than being silently force-fit.
Concept-fidelity gate — the anti-force-fit invariant
The gate generalizes the pre-existing diagram-fidelity check to every concept-type. It routes each concept to its registered renderer, never fitting a branching-logic concept into a linear flow or a data-model concept into a system map. The gate is part of the authoring-guide.md Step 1 and runs in the same select stage as the component-selection pass.
System maps — parts and connections
A system map draws anything with parts and connections: services, stores, queues, people, external systems, or the modules of a codebase. The page holds the graph as plain HTML — nested boxes and a list of connections — and a small layout engine carried inside the page places the boxes and draws the wires, so the file stays self-contained.
A boundary holds other boxes, to any depth. Open or close one in place to move between the big picture and the detail. On a large system the map opens only as many boundaries as fit comfortably (about 16 boxes), and expand all, collapse all and reset are one click away.
Async flow is dashed. Several connections between two closed boundaries merge into one thicker wire; click its "N links" label to see them. Cycles are fine: a webhook that calls back into the gateway is drawn as what it is.
Boxes and wires marked added, modified or deleted get a green, amber or rose ring and a text badge. A closed boundary shows how many changes it holds.
Under every map is the full list of connections. With JavaScript off, or if the layout fails for any reason, you still see the boxes, nested as they are, and that list; when the engine gives up on a map, it leaves one line in the browser console saying why.
Direction is automatic: left to right when that fits the page, top to bottom when it does not. The system map replaces two older diagrams, the architecture map and the dependency graph; update turns one on an older page into a system map. A page with a system map is about 28 KB larger, the size of the layout engine it carries.
Mapping a codebase
Ask document for a codebase's architecture — /walkthrough:document . architecture, or "draw a system map of this repo" — and it reads the code instead of the README. It also does this by itself when the subject is a repository root that has a build or deploy manifest and is neither a plugin nor the marketplace. Two read-only agents do the reading within a fixed budget of files and lines: system-analyzer makes claims with evidence, and system-verifier tries to refute each one against the code; refuted claims are not drawn. Click a box for the file and line where it was seen; anything supported only by indirect signals is drawn dotted and labelled inferred, and a "Gaps" section lists the directories that were not read and the claims that were dropped. The agents and the skill are told never to open, search or cite .env, key and credential files (tool, cloud and Terraform ones included) or anything outside the folder being mapped. The map shows containers by default; ask for components to open a service up. The page carries the codebase's own name — its title is <repository name> — system map — and if the reading finds nothing to map, document falls back to rendering the README and says why.
Three skills, one shared renderer
The three user-facing skills are /walkthrough:<name>, all default frontmatter — user- and intent-invokable. Typing the slash form works; so does asking in plain language. Alongside them sits one internal building block — render (user-invocable: false), consumed by the lens plugin. Two read-only agents, system-analyzer and system-verifier, do the code reading when document maps a codebase. No hooks and no shell scripts.
| Skill | Input | What it does |
|---|---|---|
| /walkthrough:create | session auto | Renders the current session from scratch through the five-stage pipeline. The optional [focus] argument scopes the synthesis. Also fires on plain-language intent — "visualize this session", "walk me through what we did", "walk me through it" (or "this" / "that"), or "make a session recap". |
| /walkthrough:update | session auto | Refreshes an existing walkthrough in place — reconstructs the prior model from the rendered HTML, folds in the spec/source files you name, and overwrites the same file. It always asks which document to refresh first; nothing is overwritten silently. It reads a system map back exactly, and turns an architecture map or a dependency graph on an older page into a system map. |
| /walkthrough:document | subject auto | Renders a subject — a plugin, the marketplace, or any path — instead of a session. README + manifest are canonical, except for a mapped codebase, where the code is the source (§ System maps). Arguments: <subject> [request] [output-path] — the output path is the last argument, and only when it ends in .html; everything else after the subject is read as a request for what to draw. This is what builds every page under site/, including this one. |
| render | internal | Renders a model already in context straight to HTML (skips gather + synthesize), reusing the same visual layer. Internal (user-invocable: false) — not a user command; it exists for other plugins to call, and the lens review companion uses it to render its findings. When the page has a system map, it returns a second line after the written path: the System map engine: … line. |
The tool that documents itself
Every page under site/ — the marketplace landing plus one per plugin — is generated by /walkthrough:document, never hand-written. This page is a rendering of walkthrough's own README + manifest. Change the README, regenerate the page.
Self-contained, tokens only
Two invariants — self-contained and tokens-only — make every walkthrough recognizably the same artifact and portable anywhere. They are non-negotiable. The rest are the guarantees that fall out of them.
All CSS, JS, and SVG live in the single HTML file. The only external resource is one Google Fonts @import — no <script src>, no <link rel=stylesheet>, no <img>, no CDN.
Never a raw hex, font, or spacing literal — everything goes through CSS custom properties. Both themes are :root token blocks; the toggle swaps token sets, not stylesheets.
One in-document toggle, viewer's choice per-view. Nothing about it requires a server or a build step.
Catalog entries used verbatim where they fit; bespoke components composed from the same primitives where they don't — passing a looks-native checklist. Empty sections are omitted rather than stubbed.
Author-written detail lives in an inert <script type="application/json"> island parsed at runtime, so every executable script is fixed boilerplate that a content typo cannot break. Escaping is by construction. Section reveal carries a 2.5s failsafe — a handler bug can't leave you staring at nothing.
Every interactive element activates on Enter and Space, not just a click — so the diagrams, cards, and detail surfaces are reachable without a mouse.
The result renders with no network beyond that one font fetch — copy the file anywhere, email it, drop it in a wiki, and it works without the plugin, without a server, and without a connection. Walkthroughs are written to .claude/walkthrough/<YYYY-MM-DD-HHMM>-<slug>.html. When a walkthrough on the same subject already exists, create asks whether to update it in place, write a new versioned file, or overwrite — rather than silently adding a -2/-3 suffix. On the first run in a repo, it offers to add the directory to .gitignore (a session artifact can contain code and prose you exchanged) and remembers your choice in settings.md.
Caveats
Opened as a file:// document on Android (which blocks local-file JavaScript) or with JavaScript off, all prose and diagrams render; only the click-to-open detail surfaces and the scroll-reveal animation are inert. A system map needs JavaScript for its picture: without it you see the boxes and the full list of connections, but no drawn wires, and that now includes a module dependency graph. There is also no print path: the document is built for on-screen exploration, with no dedicated print stylesheet, and collapsed detail won't appear in a printout.
Works in Claude Cowork
walkthrough has no hooks and no shell scripts, so it installs and runs in Claude Cowork as it does in Claude Code. Its one portable HTML file is a natural Cowork deliverable: run it and you get an explorable page you can email, drop in a wiki, or open offline. Two parts added in 1.6.0 each have a fallback, because how Cowork handles them has not been confirmed yet.
Nothing in walkthrough depends on plugin hooks — it's skills, plus two read-only agents for code reading, over a shared visual layer, so it loads and runs as a first-class citizen in Cowork, not just Claude Code.
The system-map layout engine is normally put into the page by one shell command. Where that command cannot be used, Claude types the engine into the page instead. The message after writing says which happened.
Mapping a codebase normally uses two read-only agents. Where agents cannot be dispatched, the skill does the reading and the checking itself, and the page says its claims were not independently verified.
A Cowork folder is often not a git repo, so on first run there create asks where to write — a visible walkthroughs/ folder or the hidden .claude/walkthrough/ — and remembers the choice in settings.md.
Git repos are unchanged
In a git repository — the typical Claude Code case — nothing changes: walkthroughs go to .claude/walkthrough/ with no new prompt. The location question appears only in a non-git folder.
Create, then refresh in place
/walkthrough:create architecture decisions scopes a session recap to the decisions you made; /walkthrough:update later folds in a new spec and overwrites the same file.
See a real one → a session diagnosing this marketplace’s own visibility problem and shipping the fix, rendered as a self-contained, explorable HTML doc you can open and click through.
> /walkthrough:create architecture decisions
gather read cited source files (path:line refs are real)
synthesize session model — sections, nodes, edges, decisions, files, timeline
select concept-fidelity gate → map model → components (omit empty, never stub)
assemble inline scaffold + tokens + JS + SVG + detail data
write .claude/walkthrough/2026-06-04-1430-architecture.html
→ one self-contained HTML file. Open it in any browser.
# ── later, after the spec lands ──
> /walkthrough:update specs/v2-pipeline.md
Which document to refresh?
• 2026-06-04-1430-architecture.html (only match)
→ yes
reconstruct rebuild prior model from rendered HTML (const DET)
merge revise superseded content, fold in v2-pipeline.md
write overwrite the SAME file — no new file, no backup
→ same path, now its up-to-date self.What it is — and isn't
A walkthrough is a snapshot, not a live view. Knowing the boundary keeps expectations honest.
One HTML file with everything inlined. Renders without the plugin, without a server, and without a network beyond the font fetch.
Sections, diagram nodes, decisions, and files — rendered as a composed document, not pasted from the message log.
It's a snapshot of one session at the moment you ran it — not a dashboard that updates. Re-run update to evolve it in place.
It builds a structured model first and renders that, rather than dumping the verbatim conversation.