gitvisualise

Turn any GitHub repo into an interactive, animated, narrated architecture tour: on the website, from the command line, as a Claude Code skill, or as a GitHub Action. Zero dependencies, no API keys.

Interactive diagram requires JavaScript. Static summary below.

Components

Relationships

From repo to interactive site (CLI)

  1. The skill takes charge: When you ask for an interactive architecture, Claude Code loads the skill. It does not guess: it runs the command line tool one stage at a time and checks each result. The GitHub Action drives the very same tool from a workflow.
  2. Find the repository: The tool accepts a local folder or a GitHub address. For a GitHub repo it makes a shallow clone into a cache, so the same steps work on any public repository.
  3. Scan for facts: A thin adapter walks the folder and reads files, then the scanner core records what is provably there: which file imports which, where execution starts, and which libraries are declared. These facts are the only raw material for the diagram.
  4. Draft a baseline: From those facts the generator drafts nodes, edges and a first walkthrough starting at the entry point. It works with no AI and no API key, and Claude then improves the wording and the relationships.
  5. Keep human and Claude edits: Before saving, the merge step compares the draft with any existing file. Anything marked as curated or locked is kept, so regenerating after a code change never wipes out careful work.
  6. Check every claim: The validator opens the repository and confirms that every referenced file exists, every line range is real, and every step points at a real component. Anything invented fails here, before it reaches a reader.
  7. Build the static site: The builder produces plain files: a page with the data and code snippets inlined, plus the viewer script and styles. There is nothing to install or host beyond static files, so GitHub Pages works.
  8. The viewer draws it: In the browser, the viewer reads the embedded data and lays the components out in layers. It knows nothing about this project, which is why the same viewer works for any repository.
  9. Play and listen: Press play and each step highlights its components while the browser reads the narration aloud. You can pause, step, change speed, pick a voice, or click any component to see its code.

From a pasted link to a tour (website)

  1. You paste a link: You paste a GitHub link, or pick a repository from an account. The page runs entirely in your browser. There is no server of ours in the loop, which is why it costs nothing to host.
  2. Ask GitHub for the file tree: The loader makes two requests to the public GitHub API: one to pin the exact commit, and one for the complete file listing. Pinning the commit is what keeps every Open Source link pointing at the code you analysed.
  3. Download only what matters: It skips tests, examples, tooling config and anything ignored by the repo, then downloads the shallowest source files first, up to a cap. Files come from raw.githubusercontent.com, which does not count against the API limit.
  4. Prefer the authors' own tour: If the repository already publishes a curated tour, the loader uses that instead and checks its references against the real files. If they have drifted, you are told, rather than shown stale claims as fact.
  5. The same brain as the CLI: Otherwise the loader hands the downloaded files to one function that runs the very same scanner, generator and validator the command line uses, in a Web Worker so the page stays responsive. There is one implementation with two front ends, so the website and the CLI cannot disagree.
  6. Build one self-contained page: The page renderer embeds the data and code snippets, escapes anything that came from the repository, and inlines the viewer, producing a single HTML document you can also download.
  7. Play it in a sandbox: The tour plays inside a sandboxed frame with no access to the surrounding page. Repository text is untrusted, and if you added a token, this keeps it out of reach of anything a repository could contain.
  8. Keep it or share it: Copy a share link that re-runs the analysis for anyone who opens it, or download the finished page and the architecture data. When you want narration written from your actual code, add the skill or the action to your repository.

What 1.1 added

  1. Tracing a request from client to server: A fetch or axios call is only linked to a server route when the HTTP method agrees and every path segment matches, with path parameters as the only wildcards. The generator turns each match into an http edge with evidence on both the call and the route, plus a request tour.
  2. Comparing two revisions: The loader analyses both revisions with the same node granularity, and the diff marks each component and relationship as added, removed, changed or same by id. Removed items keep their evidence pinned to the older commit, so nothing is invented.
  3. Languages are plug-ins: Each language is one small object registered in one file. It parses imports, builds an index of the repository once, and resolves an import to a file that really exists. Anything that resolves to nothing is dropped rather than guessed.
  4. Caching and shareable links: The website stores each analysed tour in IndexedDB, keyed by commit, so a repeat visit costs one request. Route helpers turn a repository, a folder, a comparison or a tour step into a link and back.
  5. Optional sign-in: Signing in with GitHub needs a client secret, so the code-for-token exchange lives in a tiny stateless function that never logs. The site only shows the button when config.js turns it on.

How the code is wired

  1. Start at app.js: Execution starts at app.js. Entry point: conventional entry filename. Follow the highlighted connections to see how the rest of the code is wired together.
  2. app.js → config.js: app.js imports config.js — 1 import (OAUTH). JavaScript file, 10 lines.
  3. Not reached by imports: These modules are not reachable from the entry point through static imports: exchange.mjs, worker.mjs, index.html, motion.js, gitvisualise.mjs, build.mjs and 43 more. They may be loaded dynamically, run separately, or be unused.

Components by role

  1. Entry (2): 2 entry parts: app.js — Entry point: conventional entry filename; gitvisualise.mjs — Entry point: package.json "bin".
  2. Ui (2): 2 ui parts: index.html — landing; index.template.html — HTML file, 101 lines.
  3. Service (36): 36 service parts: build.mjs — Node adapter: builds the static site (index.html + viewer.js + viewer.css) on disk; build-core.mjs — Pure site building: snippets + page rendering; data-core.mjs — JavaScript file, 163 lines; diff-core.mjs — JavaScript file, 105 lines; and more.
  4. Module (11): 11 general parts: exchange.mjs — JavaScript file, 180 lines; worker.mjs — JavaScript file, 7 lines; config.js — JavaScript file, 10 lines; motion.js — JavaScript file, 551 lines; and more.

Keyboard shortcuts