GitDiagram turns a GitHub URL into an AI-drawn architecture diagram, and self-hosting it means renting four services

Replacing hub with diagram in a URL is the whole entry point

GitDiagram takes a GitHub repository and returns an interactive architecture diagram with a streamed explanation next to it. The quickest way in is to edit the address bar: change github.com to gitdiagram.com in any repository URL and the diagram page for that repository opens. Each component in the diagram links to the file or directory it represents, so clicking a box takes you to the code rather than to a static picture.

The output is not locked into the web page. A diagram can be exported as PNG, or you can copy its Mermaid source and paste it into anything that renders Mermaid. Appending .md to a diagram address, as in gitdiagram.com/owner/repo.md, gives a Markdown version that is meant for AI agents to read. Adding /video to a diagram URL opens the narrated explainer for that repository if one exists. The project is built with Next.js, React, TypeScript, Tailwind CSS and Mermaid, and is credited as inspired by Romain Courtois's Gitingest.

Generation runs through OpenAI or OpenRouter and nothing else

The diagram is produced by a language model in two stages, and the provider switch in .env.example offers exactly two choices:

# OPTIONAL: choose which provider to use for generation: openai | openrouter
AI_PROVIDER=openai
# OPTIONAL: model used for both generation stages when AI_PROVIDER=openai
OPENAI_MODEL=gpt-6-luna

There is no local model option in that list. If you run GitDiagram yourself, every diagram still means sending repository information to OpenAI or to OpenRouter, and paying for the tokens. For code you are not allowed to send to a hosted model, that rules the tool out regardless of where the web app runs.

The same file exposes a cost and speed trade. Setting GENERATION_FAST_LANE to 1 runs GitDiagram-funded diagrams in OpenAI's Fast lane, which the comment prices at double the standard cost for about 3 seconds saved per diagram. Left empty, generation uses the standard lane. OPENAI_COMPLIMENTARY_GATE_ENABLED turns on a daily token cap; the example sets OPENAI_COMPLIMENTARY_DAILY_LIMIT_TOKENS to 10000000 against the gpt-6-luna model family.

Free generation is metered per IP unless you bring your own key

GitDiagram describes itself as free, and generation on the server's account is paid for by the operator. That is why the configuration throttles it. The example file sets a per-IP limit of 8 generations per 3600 seconds for diagrams billed to the server's own key:

GENERATION_RATE_LIMIT_MAX=8
GENERATION_RATE_LIMIT_WINDOW_SECONDS=3600

Callers who supply their own API key are not throttled by that limit. They still hit a looser per-IP throttle of 60 requests per 3600 seconds on /api/generate/cost and /stream, which applies to every caller and exists to bound GitHub and session work. In practice, if you are generating diagrams for many repositories in one sitting, the free path stops after a handful and your own key is how you continue. These numbers are the defaults in .env.example; an operator can change them, so the limits on a given deployment are whatever that operator configured.

The MCP server answers about public repositories only

GitDiagram runs a remote MCP server at https://gitdiagram.com/mcp with no key and no sign-in. Through it, an agent can read a public repository's architecture explanation, its components, the connections between them and the Mermaid source, search stored diagrams, and fetch explainer videos. Setup is one line per client:

# 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

ChatGPT, Windsurf, Zed, LM Studio and Goose take the same URL as a remote server. The tools are read-only and scoped to public repositories, so an agent working on your private codebase cannot use this endpoint to diagram it. Calls are capped too: MCP_RATE_LIMIT_MAX=120 per 3600 seconds per network, and when a chat app identifies the person it is calling for, each person gets that allowance and the network gets 20 times it.

Private repositories need a GitHub token handed to the app

The web app can diagram private repositories, but only after you give it a GitHub token through the Private Repos control in the header. That is the whole access model for private code: GitDiagram reads the repository with your token and then sends what it needs to the configured model provider. Anyone weighing whether to use it on proprietary code has two things to accept, the token and the hosted model call, and the second cannot be switched off.

The scope of the project is GitHub. The description, the URL trick and the MCP examples are all written around GitHub repositories and owner/repo paths. The URL swap works because GitDiagram mirrors GitHub's owner/repo layout, and the token it asks for is a GitHub token. If your code lives on GitLab or another host, none of the entry points shown for GitDiagram give you a way in, so plan on mirroring to GitHub or using something else.

A local install depends on Bun, R2, Upstash Redis and a model key

Running GitDiagram on your own machine is not a single-binary affair. It needs Bun, a Cloudflare R2 account, an Upstash Redis instance and an OpenAI or OpenRouter API key. The clone and install steps are short:

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

After filling in .env, start it with:

bun run dev

and open localhost:3000. The .env file is where the outside services come in. R2 needs R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_PUBLIC_BUCKET and R2_PRIVATE_BUCKET; Redis needs UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN; there is also a CACHE_KEY_SECRET. The consequence is that a self-hosted copy still depends on two hosted storage vendors and a hosted model, so self-hosting changes who operates the app but not where the data goes. The dev script first runs build:mcp-app, which compiles the MCP App diagram view before the dev server starts.

Explainer videos are off by default and new ones are early access

The newer feature is a narrated video of about a minute per repository. It opens with what the project is for, then shows how its main parts fit together and one decision under the hood. Videos download as MP4 in landscape or vertical 9:16, with captions burned in. Anyone can watch existing videos in the gallery, but making new videos is in early access.

On a local install the feature is disabled until you set VIDEO_EXPLAINER_ENABLED=1, NEXT_PUBLIC_VIDEO_EXPLAINER=1, ANTHROPIC_API_KEY, OPENAI_API_KEY and OPENROUTER_API_KEY. Claude or GPT writes the script and scenes, and OpenRouter supplies the voice through Gemini 3.8 Flash TTS, so videos add a third model vendor on top of diagram generation.

The Dockerfile carries a trap here. NEXT_PUBLIC_* values are compiled into the client at build time and .env files never reach the image, so NEXT_PUBLIC_VIDEO_EXPLAINER has to be passed as a build argument. Its own comment warns that without it the video controls build switched off. The image is Debian rather than Alpine because MP4 and poster renders run Chromium, which needs glibc.

Production targets Cloudflare Workers and there are no releases to pin

The hosted site is deployed on Cloudflare Workers, which explains the wrangler.jsonc variants and the cf:build and cf:deploy scripts in package.json. Docker and Railway are the fallback path, covered by railway.json and a deployment recovery document. The Dockerfile installs dependencies with oven/bun:1.3.14-slim and builds on node:22-bookworm-slim, noting that Bun's Linux ARM64 worker can crash during the Next.js TypeScript build, so that step runs under Node with type checks left to the deploy's own build.

The repository was last pushed on 2026-10-30, but it has no GitHub releases and package.json still reads version 0.1.0. Anyone self-hosting is tracking the main branch with no tagged version to roll back to. Contributions are accepted as issues or pull requests with a focused description and verification notes.

Editorial conclusion

GitDiagram suits developers who want a quick architecture map of an unfamiliar GitHub repository, and agent users who want that map over MCP with no key. It does not suit teams that need everything to stay on their own hardware: generation runs only through OpenAI or OpenRouter, and a local install also needs Cloudflare R2 and Upstash Redis. Before relying on it for private code, decide whether you are comfortable handing it a GitHub token, and note that there are no tagged releases to pin.

Frequently asked questions

Official sources

1. ahmedkhaleel2004/gitdiagram on GitHub
2. Issues
3. License: MIT
4. Project website
5. README