Point it at any GitHub repo. Get back an explainer a stranger — and their AI — actually understands.
Complex repos deserve clear introductions. This builds them, then refuses to ship until they're good.
Most repositories are opaque. Open one cold and you can't quickly tell what it is, why it matters, how it's built, or how to use it. The README is usually a wall of text written by someone who already knows the answer — so it assumes you do too.
That hurts twice over now:
- A human lands on your repo, doesn't get it in thirty seconds, and leaves.
- An AI (Claude Code, Cursor) is asked about your repo and guesses, because it has no grounded understanding of the actual source.
A longer README doesn't fix opacity. The goal is bigger than documentation:
Take someone from "I've never seen this before" to "Oh, I get why this was created, the problem it solves, what it does, why it's elegant, how it works — and I'm ready to go implement it."
That's the bar. explainmyrepo exists to clear it, on every build.
One command reads a repo and produces three things, each quality-gated:
- A live explainer web page — the link you share. A bespoke, art-directed walkthrough with a real architecture diagram and a real data-flow diagram drawn from the code itself.
- A GitHub repo you own — you're invited as a collaborator on the explainer's own repo, so you can edit it. It's yours.
- A downloadable AI knowledge pack — a drop-in
.zipcontaining a vector knowledge base of the repo, a search CLI, and an MCP server, so Claude Code or Cursor answer from the real source instead of guessing.
explainmyrepo is not a template filler and not a doc scraper. It's a single Claude Code skill that holds the judgment (the brain) plus small, pure tools that do the mechanics — with one data contract flowing between them. No brittle multi-phase pipeline.
The brain runs the repo through an ordered sequence. Each step has one job:
- Read — clone the repo and confirm it's reachable (public, private, or your own, via authenticated access).
- Understand — build a real RVF vector knowledge base from the actual code: structure-aware chunks, local 384-dim embeddings (
bge-small-en-v1.5), plus an extracted symbol index, dependency graph, and entrypoints. Then author a plain-language primer. Everything downstream is grounded in this KB — no invented capabilities. - Conceive — before writing a word, invent this repo's art direction: a visual metaphor that fits (PhotonLayer → prism, ruvn → evidence dossier, ruqu → Bloch-sphere orb), a palette, a type personality, a layout rhythm, a hero concept, and a copy voice. This is why every explainer looks different.
- Author — write the copy along a comprehension arc — the questions a newcomer actually asks, in order: What world am I in? Why does this exist? What does it do? Why is it clever? How is it built? Could I use it? How do I start? Every claim is traceable to a KB passage.
- Visualize — generate imagery on two tracks: emotional/illustrative images via
gpt-image-2(hero, problem, scenario), and crisp vector diagrams viaascii-to-svgfor structure. An architecture diagram and a data-flow diagram are mandatory on every page, drawn from the repo's real dependency graph and entrypoints — never invented. - Assemble — render the page once onto a shared design system (no incremental marker-patching), build the downloadable AI knowledge pack, and wire in SEO + social (JSON-LD, a 1200×630 social card,
llms.txtfor AI crawlers). - Grade — the quality gate. Render the real page, score it, and refine in a loop until it clears the bar (see below).
- Ship — deploy the already-great page to its own URL (Netlify by default, provider-agnostic), create the explainer GitHub repo and invite you in, set its topics + description, and email you the scorecard, both screenshots, and every link.
This is the part that makes the difference. A generic generator emits something and stops. explainmyrepo does not ship until an independent critic and a set of operator questions both pass.
The gate renders the live page in a real browser at 390px (mobile) and 1440px (desktop), takes full-page screenshots, and scores them on two independent rubrics:
- Gate A — "Do they actually get it?" (substance): visual effectiveness, storytelling, clueless-to-convinced, usefulness-to-you, completeness of the arc, and implementation confidence.
- Gate B — "Did someone who gives a shit make this?" (craft / anti-slop): typography, alignment, spacing, polish, and imagery craft — including whether the diagrams are genuinely explanatory.
To pass, on both devices, the scorecard must hit an exemplar-anchored bar: mean ≥ 90 and minimum axis ≥ 85. The bar is pinned to the project's own praised example sites (~88 headline / ~92 mean on an honest harsh grader) — not an impossible "95 on everything." The minimum-axis floor is the anti-slop catch: one weak axis (a raw ASCII diagram, a pretty-but-empty image) scores ~50 and fails the whole build.
On top of the numbers, the operator must answer YES to all five questions — a separate, independent gate:
- Would this make me believe I understand this?
- Would this make it approachable?
- Would this explain it for somebody who doesn't understand it?
- Would it give me confidence I understand the architecture?
- Does it make me smile — "oh, that's cool"?
A single axis below the bar, or a single NO, names the exact weakness, reopens just that slot, re-renders, and re-grades. Iterating over a few revisions is expected by design — it's how the build climbs to genuinely high quality. Three sets of eyes see the same pixels: the vision-model critic, the operator, and finally you (the owner) on delivery. If a repo genuinely can't reach the bar, the build says so honestly rather than shipping slop and calling it done.
The judgment lives in one place — a Claude Code skill. The same core is exposed through three thin adapters that each run the identical skill; none of them contains explainer logic of its own. Improve the brain once, and it improves everywhere.
- Claude Code plugin — run it from inside Claude Code.
- npx CLI — the one-liner below.
- Hosted website — paste a GitHub URL in the browser.
# Point it at any GitHub repo. Walk away. Get back a live page, a repo you own, and an AI pack.
npx @isovision/explainmyrepo https://github.com/owner/repoWhat you need: Node 18+, a GitHub repo URL, and your own API keys (Anthropic for the authoring brain, OpenAI for gpt-image-2 imagery).
What happens: it reads the repo, understands it, art-directs and writes the page, generates the imagery and the real architecture + data-flow diagrams, grades the result on mobile and desktop until it clears the bar, then deploys it.
What you get back: a live URL (in your terminal and by email), a GitHub repo you're a collaborator on, and the downloadable AI knowledge pack — plus the scorecard and both screenshots, so you're the final set of eyes.
Honest status: the engine is built and proven. The
npxpackage and the Claude Code plugin are being published — until that's live the one-liner above won't resolve from npm yet; today it runs as the Claude Code skill in this repo. We won't show the command as "done" until it actually installs.
The agenticow explainer below was generated end to end from ruvnet/agenticow: a captivating hero, a plain-language walkthrough, a real architecture diagram and data-flow diagram drawn from agenticow's own code, concrete use-cases, and a one-click AI knowledge pack.
The bar these are calibrated against — five hand-built explainers, five completely different looks, same engine, same gate:
| PhotonLayer — optical-AI: light computes the answer before any chip wakes up. | ruqu — a quantum-computing simulator in your browser (Rust + WASM). | ruvn — turns a question into a graded, cited evidence dossier. |
| MetaHarness — gives any project its own AI assistant that knows that project. | Agentic QE — replaces manual testing with a fleet of specialist AI agents. | agenticow — git for agent memory: copy-on-write vector branching. |
| Layer | Tool |
|---|---|
| Knowledge base | RVF single-file vector DB (@ruvector/rvf) + bge-small-en-v1.5 (local, 384-dim) |
| Imagery | gpt-image-2 (illustration) + ascii-to-svg (architecture / flow diagrams) |
| Quality gate | Playwright dual-viewport render + vision grading (Claude by default, or any vision model you configure) |
| Hosting | Netlify by default (provider-agnostic adapter) |
The full recipe lives in docs/adr/0005-skill-based-explainer-recipe.md; the domain model in docs/ddd/explainmyrepo-recipe-domain.md.
The tools in the examples above belong to Reuven Cohen / @ruvnet. explainmyrepo is an independent project that exists to help more people — and their AIs — discover, understand, and adopt great work.
Built by Stuart Kerr at ISOvision.ai.
Complex repos deserve clear introductions.