Guide · Open source

How to use GitDiagram: visualize any GitHub repo

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

GitDiagram turns a public or private GitHub repository into an interactive architecture diagram, with an AI-written explanation. It can also produce a short narrated video about the project. This guide shows you how to open a diagram from any GitHub URL, explore it, and, if you want, run the project on your own machine.

GitDiagramahmedkhaleel2004/gitdiagram · ★ 18.7k · MIT Install options & downloads

Quick start

1Take the GitHub URL. Copy the URL of the public or private repository you want to study.
2Replace hub with diagram. Change 'hub' to 'diagram' in the URL, or enter the repository on gitdiagram.com.
3Read the explanation. Read the AI-generated explanation that streams in next to the diagram.
4Follow component links. Click a component to open its linked file or directory in the repository.
5Watch or download the video. Add /video to the URL to watch a one-minute narrated overview, and download an MP4 if you need one.
6Export or copy. Export the diagram as a PNG or copy the Mermaid source.

Open a diagram from any GitHub URL

The quickest way to start is to take a GitHub repository URL and replace 'hub' with 'diagram'. That opens the diagram view for the same repository.

You can also use the front page at gitdiagram.com and enter the repository there.

Original: github.com/owner/repo
Diagram view: gitdiagram.com/owner/repo

gitdiagram.com/owner/repo

Explore the architecture diagram

Each diagram comes with an AI-generated explanation that streams in as the page loads. The explanation is generated by AI, so check important details against the code.

Components in the diagram link to files or directories in the repository. Click a component to jump to its linked code.

Read the streamed explanation alongside the diagram.
Click any component's linked file or directory to open the code.
Export the diagram as a PNG, or copy the Mermaid source.

Analyse a private repository

GitDiagram can work with private repositories. Use the Private Repos option in the header and provide a GitHub token.

Watch an explainer video

Add /video to any diagram URL to watch a narrated video of about a minute. The video covers what the project is for, what people do with it, and how its main parts fit together. You can also browse the gallery at gitdiagram.com/videos.

You can download an MP4 in landscape or vertical (9:16) format, with captions burned in. Making new videos is in early access, but anyone can watch videos that already exist.

gitdiagram.com/owner/repo/video

Use GitDiagram from AI agents

GitDiagram runs a remote MCP server at https://gitdiagram.com/mcp with no key or sign-in. Agents can read a public repository's architecture explanation, components, connections and Mermaid source, search stored diagrams, and get explainer videos.

For a repository's Markdown version, use gitdiagram.com/owner/repo.md. Setup commands for Claude Code, Codex, Gemini CLI and GitHub Copilot CLI are in the README. Other clients accept a remote MCP server with the same URL.

claude mcp add --transport http gitdiagram https://gitdiagram.com/mcp

Run GitDiagram locally

Running locally is a developer task. You need Bun, a Cloudflare R2 account, an Upstash Redis account, and an OpenAI or OpenRouter API key. The setup guide in docs/dev-setup.md covers prerequisites and configuration.

Clone the repository, install dependencies, and create your environment file. Then fill in .env using the configuration guide and start the app.

Explainer videos are off by default locally.
To enable them you set VIDEO_EXPLAINER_ENABLED=1, NEXT_PUBLIC_VIDEO_EXPLAINER=1, ANTHROPIC_API_KEY, OPENAI_API_KEY and OPENROUTER_API_KEY in .env.

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

What people use it for

Getting oriented in an unfamiliar codebase before you change anything.
Studying how a real project is structured, component by component.
Sharing a quick visual overview of a repository with a team.
Giving an AI agent architecture context for a repository through the MCP server.

Frequently asked questions

Is GitDiagram free?

The hosted site at gitdiagram.com is described as offering free interactive architecture diagrams. The project's code is released under the MIT licence. Running it yourself requires accounts and API keys for Bun-based setup, Cloudflare R2, Upstash Redis and OpenAI or OpenRouter, which may have their own costs.

Can I use GitDiagram with a private repository?

Yes. Use the Private Repos option in the header and provide a GitHub token.

How do I install GitDiagram on my computer?

Clone the GitHub repository, run bun install in the project folder, and copy .env.example to .env. You then fill in the environment file and start the app with bun run dev, which the README says you open at localhost:3000.

Are the diagrams accurate?

The diagrams and explanations are AI-generated. The README does not describe any verification process, so do not treat them as guaranteed-accurate documentation.

Can I make my own explainer videos?

Making new videos is in early access. Anyone can watch the videos that already exist.

What are good alternatives to GitDiagram?

The project lists Gitingest, Mermaid Live Editor and Sourcegraph as comparable projects. Gitingest is a tool that the README credits as an inspiration for GitDiagram.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

GitDiagram suits developers getting oriented in an unfamiliar repository, students, and teams who want a quick visual overview, especially since you can start by changing 'hub' to 'diagram' in a URL. Skip it if you need guaranteed-accurate documentation, since the output is AI-generated, or if you want to run it locally without setting up several paid services.

Install options & downloads