GitDiagram is an open-source, MIT-licensed TypeScript tool that turns any public or private GitHub repository into an interactive architecture diagram — and now into a one-minute narrated explainer video — for developers, reviewers and AI agents who need to understand a codebase quickly.

What it is

GitDiagram is a hosted web application and accompanying agent interface that reads a GitHub repository and produces an AI-generated architecture diagram with a streamed written explanation. It lives in the GitHub developer-tooling ecosystem and is built in TypeScript on Next.js, emitting Mermaid as its diagram format and exposing itself to AI clients through a remote Model Context Protocol server. Its most distinctive entry point is a URL substitution: replacing hub with diagram in any GitHub repository URL opens the diagram for that repository, so no account or installation stands between a repository and its visualisation.

The concrete problem it solves is the manual pass through a repository's directory tree that precedes almost every onboarding, review or refactor. Instead of opening files one by one to reconstruct how the parts fit together, a user sees an architecture diagram, reads a streamed explanation, and clicks any component to jump straight to its linked file or directory. For private work, a GitHub token entered through "Private Repos" in the header extends the same treatment to non-public repositories, and agents can consume the same output as Markdown or over MCP rather than rendering it visually.

Key capabilities

• Generates an interactive architecture diagram with a streamed explanation, where every component links to its file or directory in the repository.
• Produces narrated explainer videos of roughly a minute: add /video to any diagram URL, such as gitdiagram.com/owner/repo/video, and download an MP4 in landscape or vertical 9:16 with captions burned in.
• Exports diagrams as PNG, or copies the underlying Mermaid source for use elsewhere.
• Serves a Markdown version of any diagram at gitdiagram.com/owner/repo.md for agents and text-based pipelines.
• Runs as a remote MCP server at https://gitdiagram.com/mcp, requiring no key or sign-in, through which agents can read a public repository's architecture explanation, components, connections and Mermaid source, search stored diagrams, and fetch explainer videos.
• Installs into agent clients through documented commands, including the Claude Code plugin (claude plugin install gitdiagram@gitdiagram), claude mcp add --transport http gitdiagram https://gitdiagram.com/mcp, codex mcp add gitdiagram --url https://gitdiagram.com/mcp, the Gemini CLI extension, and copilot mcp add --transport http gitdiagram https://gitdiagram.com/mcp.
• Supports private repositories with a GitHub token, and accepts any GitHub repository URL through the hub-to-diagram substitution.

Who uses it and how

• Developers joining an unfamiliar codebase use the hosted site at gitdiagram.com, or the URL substitution, to get an orientation before reading source files.
• Reviewers and architects use the diagram-plus-explanation output and the PNG and Mermaid exports to share a codebase's structure in documentation or discussion.
• Agent-driven workflows consume the service programmatically: Claude Code through the plugin or MCP server, Cursor, VS Code and VS Code Insiders, Codex, Gemini CLI, GitHub Copilot CLI, and other remote-MCP clients such as ChatGPT, Windsurf, Zed, LM Studio and Goose, asking questions like "how is fastapi/fastapi structured?".
• Teams working on non-public code use the private-repository path with their own GitHub token rather than publishing the repository.
• Anyone can watch explainer videos that already exist in the gallery at gitdiagram.com/videos; creating new videos is in early access.

Getting started

The simplest route is the hosted service: open gitdiagram.com, or replace hub with diagram in any GitHub repository URL. Running GitDiagram locally requires Bun along with Cloudflare R2, Upstash Redis and an OpenAI credential, as listed in the README's local setup section.

How it compares

No comparable or competing product is named in the facts provided, so GitDiagram stands alone in this registry rather than being positioned against an alternative. The one adjacent thing it names is Mermaid, which functions as its export and interchange format rather than as a rival tool.

When to use it — and when not to

Self-hosting is not a lightweight affair: the README's local run requires Bun plus Cloudflare R2 for storage, Upstash Redis and an OpenAI credential, so a team must already operate those external services or be willing to adopt them. Anyone who cannot send repository contents to a hosted service, or to an external model provider in a local deployment, should not pick it, because both the diagrams and the explanations are generated rather than derived locally. The remaining caveats are in the README itself: video creation is in early access, private-repository support depends on a user-supplied GitHub token, and the local setup instructions as published trail off mid-list at the OpenAI credential.

# Claude Code: the plugin adds the MCP server and a /gitdiagram skill
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

# Codex
codex mcp add gitdiagram --url https://gitdiagram.com/mcp

# Gemini CLI
gemini extensions install https://github.com/ahmedkhaleel2004/gitdiagram

# GitHub Copilot CLI
copilot mcp add --transport http gitdiagram https://gitdiagram.com/mcp

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

bun run dev