GitDiagram: AI Architecture Diagrams for GitHub Repos

What GitDiagram is

GitDiagram generates an interactive architecture diagram for a GitHub repository. Point it at a public or private repo and it produces a diagram of the main components and how they connect, alongside a streamed written explanation. Each component links to the file or directory it represents, so the diagram doubles as a navigation aid into unfamiliar code. The easiest way in is a URL trick the README highlights: replace hub with diagram in any GitHub repository URL, so github.com/owner/repo becomes gitdiagram.com/owner/repo.

Two newer additions extend the idea. GitDiagram can now produce a narrated explainer video of about a minute for a repository, covering what the project is for, how its main parts fit together and one decision under the hood. And it exposes its diagrams to AI agents through a remote MCP server and Markdown versions of each diagram. The audience is developers onboarding onto a codebase, evaluating an open-source dependency, or giving a coding agent a quick structural overview of a repository.

How GitDiagram works

The architecture document describes a single Next.js application on Vercel that serves both the UI and the generation endpoints. There is no separate backend service or Postgres database. Diagram artifacts are stored in Cloudflare R2, and Upstash Redis handles quota accounting, cancellation, locks and short-lived failure state. Model calls go to OpenAI or OpenRouter, selected through an AI_PROVIDER setting.

Generation runs through a pipeline that leans heavily on validation rather than trusting model output:

1. Fetch the default branch, recursive file tree and README through the GitHub API. For very large repositories where GitHub truncates the tree, top-level folders it left out are read one level deep. Oversized READMEs are rejected before any model work.
2. Fetch bounded, integrity-checked source excerpts, favoring substantive runtime modules and spreading excerpts across long files.
3. Ask the model for a short architecture overview followed by a strict graph of groups, nodes, edges, shapes, labels and repository paths. The docs describe the default managed pipeline as a single request to an OpenAI model they call GPT-6 Luna, with extra calls reserved for structural repairs or recovering from a slow request.
4. Validate identifiers, graph connectivity, limits and every linked path against the actual repository, retrying with focused feedback when output is invalid.
5. Compile the validated graph deterministically into Mermaid with full text escaping and GitHub-only links.
6. In the browser, sanitize the source, render Mermaid with restricted settings, sanitize the resulting SVG with DOMPurify and enforce the GitHub-only link allowlist again.
7. Persist successful results so later visits reopen the diagram without another model call.

Public generations are stored by repository; private ones go into a separate R2 namespace derived with a server-side secret. Explainer videos come from the same application behind a feature flag: Claude or GPT writes the script and scenes, OpenRouter provides text-to-speech narration, and MP4s are rendered with headless Chromium and ffmpeg.

Key features

• AI-generated architecture diagrams with a streamed explanation of the codebase.
• Clickable components that jump to the linked file or directory on GitHub.
• Private repository support using a GitHub token entered through the Private Repos option in the header.
• Export diagrams as PNG or copy the Mermaid source to embed elsewhere.
• Explainer videos: roughly one-minute narrated videos, downloadable as MP4 in landscape or vertical 9:16 with burned-in captions. Add /video to a diagram URL to watch one.
• Markdown diagrams: gitdiagram.com/owner/repo.md serves a text version suited to LLMs.
• Remote MCP server at https://gitdiagram.com/mcp with no key or sign-in, letting agents read a repository's architecture explanation, components, connections and Mermaid source, search stored diagrams and fetch videos.
• Bring your own key: user-supplied API keys keep their configured model and standard service tier.

Getting started with GitDiagram

For most people the hosted site is the starting point: visit gitdiagram.com, or swap hub for diagram in a GitHub URL. To give a coding agent access, the README lists one-line setups. For Claude Code, either install the plugin (which adds the MCP server and a /gitdiagram skill) or just the server:

claude plugin marketplace add ahmedkhaleel2004/gitdiagram
claude plugin install gitdiagram@gitdiagram
# ...or just the MCP server
claude mcp add --transport http gitdiagram https://gitdiagram.com/mcp

For Codex and Gemini CLI:

codex mcp add gitdiagram --url https://gitdiagram.com/mcp
gemini extensions install https://github.com/ahmedkhaleel2004/gitdiagram

Other MCP clients can add the same remote URL. To run it locally you need Bun, a Cloudflare R2 bucket, Upstash Redis and an OpenAI or OpenRouter API key:

git clone https://github.com/ahmedkhaleel2004/gitdiagram.git
cd gitdiagram
bun install
cp .env.example .env

After filling in .env per the setup guide, start the app and open localhost:3000:

bun run dev

Explainer videos are off by default locally. Enabling them requires VIDEO_EXPLAINER_ENABLED=1, NEXT_PUBLIC_VIDEO_EXPLAINER=1 and Anthropic, OpenAI and OpenRouter keys.

Use cases

• Onboarding: get a structural map of a new codebase before reading code, then click through to the relevant directories.
• Dependency evaluation: skim how an open-source library is organized before adopting it.
• Agent context: ask an agent “how is fastapi/fastapi structured?” (the README's own example) and let it pull the answer over MCP instead of crawling the repo itself.
• Documentation: copy the Mermaid source into a README or design doc as a starting point for a maintained diagram.
• Project promotion: share a one-minute explainer video, including a vertical format for social platforms.

How GitDiagram compares

The README credits Gitingest by Romain Courtois as its inspiration.Compared with reading a repository's tree and README yourself, or asking a general-purpose chat model to summarize it, GitDiagram's distinguishing step is the validation pipeline: linked paths are checked against the real repository and the Mermaid output is compiled deterministically rather than taken verbatim from the model. Compared with hand-drawn architecture diagrams or diagram-as-code maintained by a team, GitDiagram is fast and requires no effort, but it reflects what a model infers from a bounded sample of the tree and source, so treat it as an orientation aid rather than an authoritative design document.

Things to know before adopting GitDiagram

• Hosted versus self-hosted: the public site is the main product. Self-hosting is possible under the MIT license but depends on external services (R2, Upstash Redis, an LLM provider), and Vercel is described as the only live runtime, with a Docker recipe kept for disaster recovery.
• Private code goes to an LLM: generating a diagram for a private repository sends excerpts of its source to the configured model provider. Weigh that against your organization's policies.
• Bounded view: the model only sees a bounded excerpt of the tree and selected source files, so very large repositories get a summarized picture.
• Analytics: the architecture doc lists PostHog for analytics on the hosted app.
• Video generation is in early access: anyone can watch existing videos, but creating new ones is limited for now.
• Sponsored project: the README carries a sponsor slot and a Ko-fi link.

Project activity

As of October 2026 the ahmedkhaleel2004/gitdiagram repository has roughly 17,700 stars. It was created on December 15, 2024, is written in TypeScript with Next.js, React, Tailwind CSS and Mermaid, and is licensed under MIT. The hosted service is at gitdiagram.com.