. Keep it under 900KB. Prefer inline SVG or HTML/CSS boxes and arrows over images. - Never put real keys, tokens, passwords, or connection strings in a diagram; use placeholders like <API_KEY>. Diagram refuses to publish HTML that contains one. - The page runs in a sandbox: no cookies, localStorage, or forms. - Make it look like the user's company, not generic: in a repo, reuse the app's colors, fonts, and look (and keep them in diagrams/brand.md); in a chat, ask once for their site, brand colors, or a screenshot. See the drawing guide. - Make it readable: a title and one-line subtitle, flow in one direction, labeled arrows, grouped parts, few colors used for meaning. More in https://diagram.la/docs/drawing. - How often to publish: once per request, after you've made all the changes the user asked for, not after every edit. With a local file (a repo), open it in the user's browser while you work (open / start / xdg-open) so they can review it instantly, then publish when that request is done. Without local files (a chat app), each request's result is one publish; give the same link each time, and the page the user has open updates by itself. - After publishing, look at the screenshot and warnings in the result and check the diagram against what the user asked for; fix and publish again before sharing the link if something is off. get_screenshot shows the latest version any time. - To change a diagram later, call publish_diagram again with its id. The link stays the same and every version is kept; list_versions and restore_version bring an earlier one back. - Everyone who can see a project (its owner, people added to it, and org members when the org shares) can publish new versions of its diagrams (publish_diagram with its id); only the owner changes visibility, moves, or deletes. - New diagrams are private (only the owner and project members, after Google sign-in). Pass visibility "public" only when the user wants anyone with the link to see it. - Group diagrams in a project (a lowercase slug such as "my-app"). publish_diagram creates the project if it doesn't exist. New projects are personal; pass org only if the user wants the project in their org. --- # Getting started: share AI-drawn diagrams by link Source: https://diagram.la/docs Diagram gives the diagrams your AI tools draw a home: a link you can share that updates whenever the diagram does. ## 1. Sign in [Sign in](https://diagram.la/start) with any Google account. If you're setting up a specific repo, create a [new project](https://diagram.la/new) for it first; its page walks you through the rest. ## 2. Paste one thing into your AI tool Pick the AI you use on the setup page. It shows exactly what to copy: - **Claude Code, Codex, Gemini CLI**: one command to run in your repo. It connects Diagram and starts the agent, which sets the repo up and asks what you'd like drawn. - **Cursor, VS Code, Windsurf, Zed, JetBrains, and others**: connect Diagram once, with one click or one pasted snippet. - **Claude, ChatGPT, Le Chat, Perplexity**: add Diagram as a connector once by pasting one URL into the app's settings. After that there's nothing else to paste. Diagram teaches your AI how it works, and the first request in a repo sets up a `diagrams/` folder. The connection contains your API key, so don't share it or show it on a screen share. ## 3. Ask for a diagram Just describe what you want: > Draw how a request flows through this app, from the browser to the database. > Make a diagram of our data model and share it with sam@example.com. > Update the architecture diagram now that we've added the job queue. Your tool draws it, publishes it, and gives you the link. New diagrams are private to you. See [Ideas and examples](/docs/ideas) for more to ask for. ## How it's organized - **Projects** group diagrams, usually one per repo. - **Every diagram has one link.** Updating it keeps the link and saves the old version. - **In a repo,** diagram files live in a `diagrams/` folder, so they're versioned with your code. - **Sharing is up to you:** keep a diagram private, add people by email, share with your org, or make it public. See [Sharing and privacy](/docs/sharing). --- # Share a diagram from ChatGPT or Claude as a link Source: https://diagram.la/docs/share-from-chat ChatGPT, Claude, Codex, and Cursor can all draw a diagram in seconds: an architecture map, a flowchart, a data model. Getting it to someone else is the hard part. Screenshots go stale, a shared chat exposes the whole conversation, and an HTML file in a message is awkward to open. Diagram fixes that. Your AI tool publishes the diagram to Diagram and hands you a link: - **Private by default.** Only you, until you share it with people, your team, or everyone with the link. - **One link that stays current.** Ask for a change and the same link shows the new version. Old versions are kept. - **Looks right everywhere.** It's the real diagram, not a picture: sharp at any size, zoomable, and interactive. - **Unfurls in Slack and iMessage** with its title when public, and never leaks a private title. ## From ChatGPT 1. [Sign in to Diagram](https://diagram.la/start) and choose **ChatGPT**. Copy the connector URL. 2. On chatgpt.com, open **Settings → Security and login** and turn on **Developer mode**. Then go to **chatgpt.com/plugins**, click **+**, name it Diagram, paste the URL, choose **No Authentication**, and create it. 3. In a new chat, pick **Developer mode** from the **+** menu, select Diagram, and ask: > Draw a diagram of how our signup flow works and publish it to Diagram. ChatGPT asks you to confirm the publish, then replies with the link. Custom connectors work on the ChatGPT website only, and publishing needs a plan whose developer mode allows actions that make changes (Business, Enterprise, and Edu do; on Business and Enterprise an admin has to allow developer mode). ## From Claude (desktop app or claude.ai) 1. [Sign in to Diagram](https://diagram.la/start) and choose **Claude app**. Copy the connector URL. 2. In Claude, open **Customize → Connectors**, click **+**, then **Add custom connector**. Name it Diagram, paste the URL, and click **Add**. It works on every plan; on Team and Enterprise, an org owner adds it for the organization. 3. In a new chat, click **+ → Connectors**, turn Diagram on, and ask: > Make an architecture diagram of a typical web app with a queue and a cache, and publish it to Diagram. ## From Claude Code, Codex, Cursor, or another coding agent Pick your tool (Claude Code, Codex, Cursor, VS Code, Windsurf, and more) on the [setup page](https://diagram.la/start). It shows how to connect Diagram and the first message to send. Your agent sets the repo up so diagrams live next to your code in `diagrams/`. Then just ask: > Draw how a request flows through this app and give me a link. ## Keep it up to date Because the link never changes, you can put it in a README, a pull request, or a design doc. When the code changes, ask the same tool to update the diagram, and everyone with the link sees the new version. Free for 5 projects. [See pricing](/pricing). --- # Share diagrams privately, with your team, or publicly Source: https://diagram.la/docs/sharing Everything you publish starts private. You decide who else sees it, and every project page says who can. ## Private, shared, or public - **Private** (the default): only you. - **Shared with people**: add anyone's email to a project and they can view every diagram in it after signing in with Google. They can't change anything. - **Shared with your org**: see [Orgs](#orgs). - **Public**: anyone with the link can open that one diagram, no sign-in needed. Public diagrams aren't listed anywhere and ask search engines not to index them. You don't need to remember commands. Ask your AI tool: > Share the diagrams project with sam@example.com. > Make the checkout diagram public. > Make it private again. ## One link, every version Each diagram keeps one link for as long as it exists. When it's updated, the same link shows the new version, and the old versions are kept. A page you already have open switches to the new version by itself, so you can leave it open while your AI works. A link you pasted into a pull request last month shows today's diagram. ## Editing together Anyone who can see a project can edit its diagrams: the owner, people they added, and everyone in the org when the org shares its projects. Open the diagram and press **Edit**, pick the AI tool you use (Claude, ChatGPT, Cursor, Codex, and others), copy the prompt, and paste it there. Your AI loads the diagram, asks what to change, and publishes a new version at the same link. Every earlier version is kept, so nothing gets lost: press **History** on a diagram to see who changed it and when, and click any version to view it. Only the owner can make a diagram public or private, move it, or delete it. People who only have the public link see the current version, never the history. ## Orgs Orgs let a team see each other's projects, but only when someone chooses to share them. - **Who's in an org:** everyone who signs in with an address at your company's email domain, plus people an org admin invites by email, such as contractors. - **Projects stay personal** until you move one into the org. Pick the org when you create the project, or press **Move** on any of your projects (on your dashboard, an org page, or the project's Settings) and choose an org or Personal. You can move a project between orgs or back to personal any time, and single diagrams between your projects. Links never change. - **Sharing is a switch, off by default.** An org admin ticks **Everyone in Acme can see every org project** on the org page. While it's off, org projects are as private as personal ones. Joining an org is free. Creating one comes with [Pro](/pricing). ## Link previews Paste a public diagram's link into Slack, iMessage, Discord, LinkedIn, or X and it unfurls with its title. Making a diagram public shares that diagram only: its page and preview never show the project it's in, who owns it, or your org. Private diagrams unfurl as a generic card, so a pasted link never reveals what's behind it. ## Is it safe? - Diagrams run in a sealed-off sandbox. A diagram can't see your account, read your cookies, or act as you, even if its code tried to. - Your API key is shown once. If it leaks, revoke it on the [API keys](https://diagram.la/keys) page and make a new one. - Nobody at Diagram, including our own admin accounts, can open your private diagrams. More detail for developers: [Security](/docs/security). --- # Diagram ideas to ask Claude, ChatGPT, and Codex for Source: https://diagram.la/docs/ideas If you can describe it, your AI tool can draw it. A few ideas to get started: ## For a codebase > Draw the architecture of this repo: the main services, what they talk to, and the external APIs. > Show how a login request flows from the browser through our API to the database, step by step. > Make an entity diagram of our database tables and how they relate. > Diagram the deploy pipeline from a merged pull request to production. > We just added a job queue. Update the architecture diagram to include it. ## For planning and explaining > Draw the states an order goes through, from cart to delivered, with what triggers each change. > Make a timeline of the migration plan for next quarter. > Turn this list of steps into a flowchart I can send to the team. ## Making it better Ask for changes the way you'd ask a designer: > Group the third-party services together and make the database stand out. > Label every arrow with what's being sent. > Add a legend, and make it work in dark mode. > Make each box clickable to show more detail. ## What a diagram can be Anything a web page can show: boxes and arrows, sequence diagrams, timelines, charts, hand-drawn-style sketches, and interactive diagrams you can hover and click. Your tool picks the right approach, often [Mermaid](https://mermaid.js.org) for flowcharts and sequence diagrams, or custom SVG for architecture maps. ## A Mermaid example For the curious, this is roughly what a simple diagram file looks like. You never have to write this yourself. ```html <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>Checkout flow

# Diagram > Diagram hosts diagrams drawn by AI at permanent, private or public links. Publish from Claude, ChatGPT, Claude Code, Codex, Cursor, or CI, and every update lands at the same URL. ## Quick rules for agents Diagram (https://diagram.la) hosts self-contained HTML diagrams at permanent links. To share a diagram: draw it as ONE complete HTML document and call publish_diagram. It returns a URL; give that URL to the user. - Working in a repo (you can read and write its files)? If it has no diagrams/README.md yet, set it up before the first publish: call list_projects, use the project whose slug matches the repo folder or that the user named, and otherwise ask the user which project to use (suggest the folder name in lowercase with dashes). Then call setup_repo with it and write the files it returns. Do the same when the user asks to set up Diagram. In a repo that has diagrams/README.md, read it first and follow it: save each diagram in diagrams/ and keep its id in a tag so later publishes update the same link. - Put everything inline (CSS, JS, SVG). Scripts from a CDN such as https://cdn.jsdelivr.net work (Mermaid: import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'). - Include a . Keep it under 900KB. Prefer inline SVG or HTML/CSS boxes and arrows over images. - Never put real keys, tokens, passwords, or connection strings in a diagram; use placeholders like <API_KEY>. Diagram refuses to publish HTML that contains one. - The page runs in a sandbox: no cookies, localStorage, or forms. - Make it look like the user's company, not generic: in a repo, reuse the app's colors, fonts, and look (and keep them in diagrams/brand.md); in a chat, ask once for their site, brand colors, or a screenshot. See the drawing guide. - Make it readable: a title and one-line subtitle, flow in one direction, labeled arrows, grouped parts, few colors used for meaning. More in https://diagram.la/docs/drawing. - How often to publish: once per request, after you've made all the changes the user asked for, not after every edit. With a local file (a repo), open it in the user's browser while you work (open / start / xdg-open) so they can review it instantly, then publish when that request is done. Without local files (a chat app), each request's result is one publish; give the same link each time, and the page the user has open updates by itself. - After publishing, look at the screenshot and warnings in the result and check the diagram against what the user asked for; fix and publish again before sharing the link if something is off. get_screenshot shows the latest version any time. - To change a diagram later, call publish_diagram again with its id. The link stays the same and every version is kept; list_versions and restore_version bring an earlier one back. - Everyone who can see a project (its owner, people added to it, and org members when the org shares) can publish new versions of its diagrams (publish_diagram with its id); only the owner changes visibility, moves, or deletes. - New diagrams are private (only the owner and project members, after Google sign-in). Pass visibility "public" only when the user wants anyone with the link to see it. - Group diagrams in a project (a lowercase slug such as "my-app"). publish_diagram creates the project if it doesn't exist. New projects are personal; pass org only if the user wants the project in their org. --- # Getting started: share AI-drawn diagrams by link Source: https://diagram.la/docs Diagram gives the diagrams your AI tools draw a home: a link you can share that updates whenever the diagram does. ## 1. Sign in [Sign in](https://diagram.la/start) with any Google account. If you're setting up a specific repo, create a [new project](https://diagram.la/new) for it first; its page walks you through the rest. ## 2. Paste one thing into your AI tool Pick the AI you use on the setup page. It shows exactly what to copy: - **Claude Code, Codex, Gemini CLI**: one command to run in your repo. It connects Diagram and starts the agent, which sets the repo up and asks what you'd like drawn. - **Cursor, VS Code, Windsurf, Zed, JetBrains, and others**: connect Diagram once, with one click or one pasted snippet. - **Claude, ChatGPT, Le Chat, Perplexity**: add Diagram as a connector once by pasting one URL into the app's settings. After that there's nothing else to paste. Diagram teaches your AI how it works, and the first request in a repo sets up a `diagrams/` folder. The connection contains your API key, so don't share it or show it on a screen share. ## 3. Ask for a diagram Just describe what you want: > Draw how a request flows through this app, from the browser to the database. > Make a diagram of our data model and share it with sam@example.com. > Update the architecture diagram now that we've added the job queue. Your tool draws it, publishes it, and gives you the link. New diagrams are private to you. See [Ideas and examples](/docs/ideas) for more to ask for. ## How it's organized - **Projects** group diagrams, usually one per repo. - **Every diagram has one link.** Updating it keeps the link and saves the old version. - **In a repo,** diagram files live in a `diagrams/` folder, so they're versioned with your code. - **Sharing is up to you:** keep a diagram private, add people by email, share with your org, or make it public. See [Sharing and privacy](/docs/sharing). --- # Share a diagram from ChatGPT or Claude as a link Source: https://diagram.la/docs/share-from-chat ChatGPT, Claude, Codex, and Cursor can all draw a diagram in seconds: an architecture map, a flowchart, a data model. Getting it to someone else is the hard part. Screenshots go stale, a shared chat exposes the whole conversation, and an HTML file in a message is awkward to open. Diagram fixes that. Your AI tool publishes the diagram to Diagram and hands you a link: - **Private by default.** Only you, until you share it with people, your team, or everyone with the link. - **One link that stays current.** Ask for a change and the same link shows the new version. Old versions are kept. - **Looks right everywhere.** It's the real diagram, not a picture: sharp at any size, zoomable, and interactive. - **Unfurls in Slack and iMessage** with its title when public, and never leaks a private title. ## From ChatGPT 1. [Sign in to Diagram](https://diagram.la/start) and choose **ChatGPT**. Copy the connector URL. 2. On chatgpt.com, open **Settings → Security and login** and turn on **Developer mode**. Then go to **chatgpt.com/plugins**, click **+**, name it Diagram, paste the URL, choose **No Authentication**, and create it. 3. In a new chat, pick **Developer mode** from the **+** menu, select Diagram, and ask: > Draw a diagram of how our signup flow works and publish it to Diagram. ChatGPT asks you to confirm the publish, then replies with the link. Custom connectors work on the ChatGPT website only, and publishing needs a plan whose developer mode allows actions that make changes (Business, Enterprise, and Edu do; on Business and Enterprise an admin has to allow developer mode). ## From Claude (desktop app or claude.ai) 1. [Sign in to Diagram](https://diagram.la/start) and choose **Claude app**. Copy the connector URL. 2. In Claude, open **Customize → Connectors**, click **+**, then **Add custom connector**. Name it Diagram, paste the URL, and click **Add**. It works on every plan; on Team and Enterprise, an org owner adds it for the organization. 3. In a new chat, click **+ → Connectors**, turn Diagram on, and ask: > Make an architecture diagram of a typical web app with a queue and a cache, and publish it to Diagram. ## From Claude Code, Codex, Cursor, or another coding agent Pick your tool (Claude Code, Codex, Cursor, VS Code, Windsurf, and more) on the [setup page](https://diagram.la/start). It shows how to connect Diagram and the first message to send. Your agent sets the repo up so diagrams live next to your code in `diagrams/`. Then just ask: > Draw how a request flows through this app and give me a link. ## Keep it up to date Because the link never changes, you can put it in a README, a pull request, or a design doc. When the code changes, ask the same tool to update the diagram, and everyone with the link sees the new version. Free for 5 projects. [See pricing](/pricing). --- # Share diagrams privately, with your team, or publicly Source: https://diagram.la/docs/sharing Everything you publish starts private. You decide who else sees it, and every project page says who can. ## Private, shared, or public - **Private** (the default): only you. - **Shared with people**: add anyone's email to a project and they can view every diagram in it after signing in with Google. They can't change anything. - **Shared with your org**: see [Orgs](#orgs). - **Public**: anyone with the link can open that one diagram, no sign-in needed. Public diagrams aren't listed anywhere and ask search engines not to index them. You don't need to remember commands. Ask your AI tool: > Share the diagrams project with sam@example.com. > Make the checkout diagram public. > Make it private again. ## One link, every version Each diagram keeps one link for as long as it exists. When it's updated, the same link shows the new version, and the old versions are kept. A page you already have open switches to the new version by itself, so you can leave it open while your AI works. A link you pasted into a pull request last month shows today's diagram. ## Editing together Anyone who can see a project can edit its diagrams: the owner, people they added, and everyone in the org when the org shares its projects. Open the diagram and press **Edit**, pick the AI tool you use (Claude, ChatGPT, Cursor, Codex, and others), copy the prompt, and paste it there. Your AI loads the diagram, asks what to change, and publishes a new version at the same link. Every earlier version is kept, so nothing gets lost: press **History** on a diagram to see who changed it and when, and click any version to view it. Only the owner can make a diagram public or private, move it, or delete it. People who only have the public link see the current version, never the history. ## Orgs Orgs let a team see each other's projects, but only when someone chooses to share them. - **Who's in an org:** everyone who signs in with an address at your company's email domain, plus people an org admin invites by email, such as contractors. - **Projects stay personal** until you move one into the org. Pick the org when you create the project, or press **Move** on any of your projects (on your dashboard, an org page, or the project's Settings) and choose an org or Personal. You can move a project between orgs or back to personal any time, and single diagrams between your projects. Links never change. - **Sharing is a switch, off by default.** An org admin ticks **Everyone in Acme can see every org project** on the org page. While it's off, org projects are as private as personal ones. Joining an org is free. Creating one comes with [Pro](/pricing). ## Link previews Paste a public diagram's link into Slack, iMessage, Discord, LinkedIn, or X and it unfurls with its title. Making a diagram public shares that diagram only: its page and preview never show the project it's in, who owns it, or your org. Private diagrams unfurl as a generic card, so a pasted link never reveals what's behind it. ## Is it safe? - Diagrams run in a sealed-off sandbox. A diagram can't see your account, read your cookies, or act as you, even if its code tried to. - Your API key is shown once. If it leaks, revoke it on the [API keys](https://diagram.la/keys) page and make a new one. - Nobody at Diagram, including our own admin accounts, can open your private diagrams. More detail for developers: [Security](/docs/security). --- # Diagram ideas to ask Claude, ChatGPT, and Codex for Source: https://diagram.la/docs/ideas If you can describe it, your AI tool can draw it. A few ideas to get started: ## For a codebase > Draw the architecture of this repo: the main services, what they talk to, and the external APIs. > Show how a login request flows from the browser through our API to the database, step by step. > Make an entity diagram of our database tables and how they relate. > Diagram the deploy pipeline from a merged pull request to production. > We just added a job queue. Update the architecture diagram to include it. ## For planning and explaining > Draw the states an order goes through, from cart to delivered, with what triggers each change. > Make a timeline of the migration plan for next quarter. > Turn this list of steps into a flowchart I can send to the team. ## Making it better Ask for changes the way you'd ask a designer: > Group the third-party services together and make the database stand out. > Label every arrow with what's being sent. > Add a legend, and make it work in dark mode. > Make each box clickable to show more detail. ## What a diagram can be Anything a web page can show: boxes and arrows, sequence diagrams, timelines, charts, hand-drawn-style sketches, and interactive diagrams you can hover and click. Your tool picks the right approach, often [Mermaid](https://mermaid.js.org) for flowcharts and sequence diagrams, or custom SVG for architecture maps. ## A Mermaid example For the curious, this is roughly what a simple diagram file looks like. You never have to write this yourself. ```html <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>Checkout flow

flowchart LR
  Cart --> Checkout
  Checkout -->|card| Stripe
  Checkout -->|invoice| Billing
  Stripe --> Receipt
  Billing --> Receipt

``` --- # Diagram FAQ Source: https://diagram.la/docs/faq ## What is Diagram? A home for diagrams your AI tools draw. Ask Claude, ChatGPT, Codex, Cursor, or another AI tool for a diagram, and Diagram gives it a link that always shows the latest version. ## Which AI tools work with it? Coding agents (Claude Code, Codex CLI and app, Gemini CLI, OpenCode), editors (Cursor, VS Code with Copilot, Windsurf, Cline, Zed, JetBrains), and chat apps (Claude desktop, claude.ai, ChatGPT, and any app that takes an MCP connector). Setup is one paste. See [Getting started](/docs). ## Does it cost anything? The free plan covers 5 projects with up to 100 diagrams each, which is plenty for most people. Pro is $5/month for 100 projects of 1000 diagrams each, plus orgs. The limits keep the site free of spam. See [pricing](/pricing). ## Who can see my diagrams? Only you, until you share them. You can add people by email, share with your org, or make a single diagram public. See [Sharing and privacy](/docs/sharing). ## Why not paste a screenshot? A screenshot is out of date the moment things change. A Diagram link always shows the latest version, stays sharp and interactive, and can be updated by the same tool that changed the code. ## Can I edit a diagram on the website? No. You change a diagram by asking your AI tool, which keeps the diagram next to the code it describes. ## Can I delete a diagram? Yes. Ask your tool to delete it. The diagram and all its versions are removed and the link stops working. ## Is it safe to open someone's diagram? Yes. Diagrams run in a sealed-off sandbox and can't see your account or act as you. ## Is there an API? Yes, for developers and agents. See the [developer reference](/docs/reference). --- # Developer reference Source: https://diagram.la/docs/reference You don't need any of this to use Diagram: the setup prompt and connectors hand it to your AI tool. It's here for developers who want the details. - [Repo setup and CI](/docs/agents): the `setup_repo` tool, the `diagrams/` folder, keeping links current from CI. - [Connecting tools by hand](/docs/chat-apps): MCP URLs and per-tool configuration. - [Diagram file rules](/docs/drawing): what a diagram file can contain and how to make it readable. - [HTTP API](/docs/api): endpoints, examples, errors, and limits. - [Security](/docs/security): how diagrams are sandboxed and how keys work. For agents, everything is in one file: [llms-full.txt](https://diagram.la/llms-full.txt). There's also a short index at [llms.txt](https://diagram.la/llms.txt) and an [OpenAPI description](https://diagram.la/openapi.json). --- # Repo setup and CI Source: https://diagram.la/docs/agents Coding agents like Claude Code, Codex, Cursor, and Gemini CLI connect to Diagram over MCP, the same way chat apps do. The agent draws a diagram as HTML, saves it in the repo, publishes it, and hands you a link. The next time it changes the diagram, the link stays the same. ## Connect the agent Sign in and open [Get started](https://diagram.la/start) (or a project's page), then pick your tool. For terminal agents it's one command that connects Diagram and starts the agent with the first message. For editors it's one click or a short settings snippet. Manual steps for every tool are in [Connect your app](/docs/chat-apps). ## Set up the repo The first message asks the agent to call the Diagram tool `setup_repo` for your project. It creates the project if needed and returns the files for the agent to write: - **`diagrams/`** for the diagram files, with a `diagrams/README.md` that tells agents how to draw and publish them (below). - **A short section in `CLAUDE.md` and/or `AGENTS.md`** pointing agents at that README. `AGENTS.md` is created if neither exists. Nothing secret goes in the repo: the key lives in the tool's MCP settings. Each published file keeps its diagram id in a `` tag, so any agent that publishes it again updates the same link. Commit the whole folder. The section added to `CLAUDE.md` / `AGENTS.md`: ~~~md ## Diagrams This repo publishes diagrams to Diagram, project `my-app`. They live in `diagrams/`. Before drawing or changing one, read `diagrams/README.md` and follow it. ~~~ `diagrams/README.md`: ~~~md # Diagrams This folder holds the diagrams for this repo. Each one is published to Diagram in the project `my-app`: https://diagram.la/p/my-app ## For agents Publish with the Diagram MCP tools (`publish_diagram`, `get_diagram`). If they aren't available, ask the user to connect Diagram. In Claude Code that's `claude mcp add -s user --transport http diagram https://diagram.la/mcp`, then `/mcp` → diagram → Authenticate to sign in with Google; for other tools, https://diagram.la/start 1. **One file per diagram.** Save it here as a single self-contained HTML file named after what it shows, e.g. `diagrams/architecture.html` or `diagrams/checkout-flow.html`. 2. **Everything inline.** CSS, JS, and SVG go in the file. Scripts from a CDN such as jsDelivr are fine (Mermaid: `import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'`). The page runs in a sandbox, so it can't load other files from the repo, use cookies or localStorage, or submit forms. 3. **Add a ``.** It becomes the diagram's title and the text in link previews. 4. **Match the brand.** Diagrams should look like this product. The first time, read the app's styles (CSS variables, theme or Tailwind config, fonts, logo) and write `diagrams/brand.md` with its colors, fonts, and light or dark look; if it's unclear, ask the user what the product looks like. After that, style every diagram from `diagrams/brand.md` (inline, since diagrams can't load repo files). Guide: https://diagram.la/docs/drawing 5. **Keep it small and readable.** Under 900KB. Prefer inline SVG or HTML/CSS boxes and arrows over embedded images. Give it a title and subtitle, flow in one direction, label every arrow, group related parts. Full guide: https://diagram.la/docs/drawing 6. **Show it locally while you work.** After writing or changing a diagram, open the file in the user's browser so they see it right away: `open diagrams/<name>.html` on macOS, `start diagrams\<name>.html` on Windows, `xdg-open diagrams/<name>.html` on Linux. Open it the first time; after that, tell them to refresh the tab. Edit as many times as the request needs. 7. **Publish once per request.** When you've finished the changes the user asked for (not after every edit), publish with `publish_diagram`, passing the whole file as `html`. The cloud copy is then never more than one request behind, and each version in its history is one request: - If the file has `<meta name="diagram-id" content="...">`, pass that value as `id`. The link stays the same and a new version is kept. - If not, pass `project: "my-app"`, then add `<meta name="diagram-id" content="<the returned id>">` to the file's `<head>` so later publishes update it. Give the user the link it returns. Anyone with the link open sees the new version appear on its own. 8. **Private by default.** Only make a diagram public when the user asks (`set_visibility`). 9. **No keys in the repo.** The Diagram connection lives in the AI tool's MCP settings. ~~~ ## What a good diagram file looks like - One `.html` file with everything inline, or scripts loaded from a CDN such as jsDelivr. The page can't load files that sit next to it in the repo. - A `<title>`. It becomes the diagram's title, and public diagrams show it in link previews. - 900KB or less. Inline SVG is usually far smaller than embedded images. - It shouldn't need cookies, `localStorage`, or forms. Diagrams run in a sandbox that blocks those (see [Security](/docs/security)). Mermaid, D2, Graphviz, Excalidraw exports, hand-written SVG, and plain HTML with CSS all work. The [Mermaid guide](/docs/ideas) has a template. ## Keep links current from CI CI can't use MCP, so it publishes over the [HTTP API](/docs/api). Each file's `diagram-id` tag says which diagram it is, so CI updates the same links your agent published. Add an API key as a repository secret and publish changed diagrams on every merge. For GitHub Actions: ```yaml name: diagrams on: push: branches: [main] paths: ['diagrams/**'] jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Publish diagrams env: DIAGRAM_API_KEY: ${{ secrets.DIAGRAM_API_KEY }} run: | for f in diagrams/*.html; do id=$(grep -o 'name="diagram-id" content="[^"]*"' "$f" | sed 's/.*content="//; s/"$//') if [ -z "$id" ]; then echo "skip $f (not published yet)"; continue; fi jq -Rs '{html: .}' "$f" | curl -fsS -X PUT "https://diagram.la/api/v1/diagrams/$id" \ -H "Authorization: Bearer $DIAGRAM_API_KEY" -H 'content-type: application/json' -d @- > /dev/null echo "published $f" done ``` Publishing unchanged HTML is a no-op, so sending every file on every run is safe. Files without a `diagram-id` tag are skipped: publish new diagrams from your agent first, then commit them with their tag. ## Over HTTP Anything that can make an HTTP request can publish. `GET https://diagram.la/api/v1` returns a plain-text-friendly index of every endpoint, and there is a full [OpenAPI description](https://diagram.la/openapi.json). See the [API reference](/docs/api) for `curl` examples. --- # Connecting tools by hand Source: https://diagram.la/docs/chat-apps Diagram runs a remote [MCP](https://modelcontextprotocol.io) server, so any app that supports MCP connectors can publish diagrams. It's the main way to connect every tool, chat apps and coding agents alike. You describe what you want, the model draws it as HTML, and Diagram hands back a link. **The fastest way:** sign in at [https://diagram.la](https://diagram.la) and pick your tool on the getting-started page. ## Your MCP address | Client | Address | Sign-in | | --- | --- | --- | | Tools that support MCP sign-in (Claude Code, Codex, Gemini CLI, Cursor, VS Code, Zed, OpenCode, the Claude app, ChatGPT, Le Chat) | `https://diagram.la/mcp` | A browser tab opens the first time: sign in with Google and click Allow. No key to copy. | | Tools that only take a URL and can't sign in | `https://diagram.la/mcp/<your key>` | The key is in the address | | Scripts and clients that send headers | `https://diagram.la/mcp` | `Authorization: Bearer <your key>` | Every tool you sign in shows up on the [API keys](https://diagram.la/keys) page, where you can disconnect it. Treat an address with a key in it like a password; if it leaks, revoke the key there. Sign-in follows the MCP authorization spec: OAuth 2.1 with PKCE and dynamic client registration, discovered from `https://diagram.la/.well-known/oauth-protected-resource/mcp`. ## Tools | Tool | What it does | | --- | --- | | `publish_diagram` | Create a diagram from HTML, or update one by `id`. Creates the project if needed. Returns the link, plus a screenshot and layout warnings so the AI can check its work. | | `setup_repo` | Set a repo up to keep diagrams in `diagrams/` for a project. | | `list_projects` | Projects you own or were added to. | | `list_diagrams` | A project's diagrams and links. | | `get_diagram` | A diagram's details and, with `include_html`, its HTML for editing. | | `get_screenshot` | A screenshot of a diagram (current or an earlier version) with layout warnings, to review it before sharing. | | `list_versions` | A diagram's history: who published each version and when. | | `restore_version` | Bring back an earlier version as the newest one, at the same link. | | `set_visibility` | Make a diagram public or private. | | `move_diagram` | Move a diagram to another of your projects. The link stays the same. | | `list_orgs` | Orgs you belong to and whether they share projects. | | `set_project_org` | Move a project into an org or back to personal. | | `share_project` | Add someone to a project (they can see and edit its diagrams), or remove them. | | `delete_diagram` | Delete a diagram and its versions. | The server also sends instructions on how to draw a diagram that works well on Diagram, so you don't have to explain the format. ## Coding agents ### Claude Code Run this in a terminal in your repo. It connects Diagram and starts Claude Code with the first message: ```sh claude mcp remove -s user diagram ; claude mcp add -s user --transport http diagram https://diagram.la/mcp ; claude ``` When Claude Code starts, type /mcp, pick diagram, and choose Authenticate: sign in with Google in the browser tab that opens. ### Codex CLI Run this in a terminal in your repo. It connects Diagram and starts Codex CLI with the first message: ```sh codex mcp remove diagram ; codex mcp add diagram --url https://diagram.la/mcp ; codex "Set up Diagram for this repo, then ask me what to draw. If you don't have the Diagram tools, tell me the connection didn't work." ``` Codex opens a browser tab as soon as it adds Diagram: sign in with Google and click Allow. ### Codex app 1. In the Codex app, open Settings → MCP servers → Add server, choose Streamable HTTP, paste the URL from this snippet, save, and restart. Or add the snippet to ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows), which the Codex CLI and IDE extension share: ``` [mcp_servers.diagram] url = "https://diagram.la/mcp" ``` 2. Open your repo in the Codex app and start a new task, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. After adding it, choose Sign in next to diagram in Settings → MCP servers: sign in with Google and click Allow. ### Gemini CLI Run this in a terminal in your repo. It connects Diagram and starts Gemini CLI with the first message: ```sh gemini mcp remove -s user diagram ; gemini mcp add -s user --transport http diagram https://diagram.la/mcp ; gemini -i "Set up Diagram for this repo, then ask me what to draw. If you don't have the Diagram tools, tell me the connection didn't work." ``` When Gemini first connects, a browser tab opens: sign in with Google and click Allow. ### OpenCode 1. Add this to ~/.config/opencode/opencode.json (merge it if the file already has an "mcp" section): ``` { "$schema": "https://opencode.ai/config.json", "mcp": { "diagram": { "type": "remote", "url": "https://diagram.la/mcp", "enabled": true } } } ``` 2. Run opencode in your repo, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. Then run opencode mcp auth diagram: a browser tab opens to sign in with Google. ## Editors ### Cursor 1. Use the **Add to Cursor** button on the setup page. Or add this to ~/.cursor/mcp.json: ``` { "mcpServers": { "diagram": { "url": "https://diagram.la/mcp" } } } ``` 2. Open your repo and switch the chat to Agent, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. In Cursor Settings → MCP, click Connect (or Needs login) next to diagram: sign in with Google and click Allow. ### VS Code + Copilot 1. Use the **Add to VS Code** button on the setup page. Or run "MCP: Add Server" from the Command Palette, choose HTTP, paste this URL, and choose Global. VS Code asks you to trust the server the first time it starts: ``` https://diagram.la/mcp ``` 2. Open your repo and switch Copilot Chat to Agent mode, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. When VS Code starts the server, it asks to sign in: allow it, then sign in with Google and click Allow. ### Windsurf 1. Click the MCPs icon at the top right of the Cascade panel, open the raw config (~/.codeium/windsurf/mcp_config.json), and add this. The Devin agent in Windsurf reads the same file: ``` { "mcpServers": { "diagram": { "url": "https://diagram.la/mcp/dgm_YOUR_KEY" } } } ``` 2. Open your repo in Windsurf and open Cascade, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. This address has your key in it; get yours on the setup page. ### Cline 1. In Cline, click the MCP Servers icon → Remote Servers. Name it diagram, paste this URL, set Transport Type to Streamable HTTP, and click Add Server: ```text https://diagram.la/mcp/dgm_YOUR_KEY ``` 2. Start a new Cline task in your repo, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. This address has your key in it; get yours on the setup page. ### Zed 1. In Zed, open Settings → AI → MCP Servers → Add Server → Add Remote Server, or add this to your settings file (zed: open settings file). A green dot means it’s connected: ``` { "context_servers": { "diagram": { "url": "https://diagram.la/mcp" } } } ``` 2. Open your repo in Zed and open the Agent Panel, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. The first time, a browser tab opens: sign in with Google and click Allow. ### JetBrains 1. For AI Assistant: Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add, paste this as JSON, choose Global, then OK and Apply. For Junie, put the same JSON in ~/.junie/mcp/mcp.json: ``` { "mcpServers": { "diagram": { "url": "https://diagram.la/mcp/dgm_YOUR_KEY" } } } ``` 2. Open your repo and open AI Assistant or Junie in agent mode, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. This address has your key in it; get yours on the setup page. ## Chat apps ### Claude app 1. In claude.ai or the Claude desktop app: Customize → Connectors → + → Add custom connector. Name it Diagram, paste this URL, leave Advanced settings empty, and click Add: ```text https://diagram.la/mcp ``` 2. In a new chat, click + → Connectors and turn on Diagram, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. After adding it, click Connect next to Diagram: sign in with Google and click Allow. Works on every Claude plan (Free allows one custom connector). On Team and Enterprise, an org owner adds custom connectors under Organization settings → Connectors. ### ChatGPT 1. On chatgpt.com: Settings → Security and login → turn on Developer mode. Then go to chatgpt.com/plugins, click +, name it Diagram, paste this as the server URL, choose OAuth, and create it: ```text https://diagram.la/mcp ``` 2. In a new chat, pick Developer mode from the + menu and select Diagram (ChatGPT asks you to confirm each publish), then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. ChatGPT then sends you to sign in with Google and click Allow. Web only (chatgpt.com). Publishing needs a plan whose developer mode allows write tools: Business, Enterprise, or Edu for sure; OpenAI’s docs disagree on Plus and Pro. On Business and Enterprise, an admin has to allow developer mode. ### Le Chat 1. In Le Chat: Connectors → + Add Connector → Custom MCP Connector. Name it Diagram, paste this URL, and click Connect: ```text https://diagram.la/mcp ``` 2. In a new chat, enable Diagram in the tools menu, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. Le Chat detects the sign-in and opens it: sign in with Google and click Allow. ### Perplexity 1. In Perplexity: Account settings → Connectors → + Custom connector → Remote. Name it Diagram, paste this URL, set Authentication to None and Transport to Streamable HTTP, add it, then click its card to turn it on: ```text https://diagram.la/mcp/dgm_YOUR_KEY ``` 2. Start a new thread with Diagram turned on, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. This address has your key in it; get yours on the setup page. Needs Perplexity Pro, Max, or Enterprise. ### Anything else 1. Any app or agent that takes a remote MCP server (Streamable HTTP): add a server named diagram with this URL: ```text https://diagram.la/mcp/dgm_YOUR_KEY ``` 2. Start a new chat, then ask for a diagram in plain words. In a repo, the first request also sets up `diagrams/`. This address has your key in it; get yours on the setup page. --- # Drawing diagrams that work on Diagram Source: https://diagram.la/docs/drawing A diagram on Diagram is one HTML file that a browser renders. You describe what you want in plain language; the agent turns it into that file. This page is what the agent should know to do it well. ## The file - **One self-contained HTML document** per diagram, with a `<title>` (it becomes the diagram's title and link-preview text). - **Inline everything**: CSS in `<style>`, JS in `<script>`, drawings as inline `<svg>`. Scripts, styles, and fonts from a CDN such as jsDelivr or Google Fonts are fine. Files next to it in the repo are not reachable. - **Under 900KB.** Inline SVG is small; embedded bitmaps are not. - **Sandboxed**: no cookies, `localStorage`, `sessionStorage`, IndexedDB, or form submission. Clicks, hover, zoom, animation, and links that open a new tab all work. See [Security](/docs/security). - **Fills the frame**: the page is shown full-window. Center the drawing, let it scale with the viewport (`viewBox` on SVG, `max-width: 100%`), and leave some margin. ## Pick a technique | Want | Use | Notes | | --- | --- | --- | | Flowcharts, sequence, state, ER, class, Gantt, timelines, mind maps | [Mermaid](https://mermaid.js.org) from jsDelivr | Fastest to write and edit. See the [Mermaid guide](/docs/ideas). | | Architecture and system maps with a custom look | Hand-written inline SVG, or HTML boxes with SVG arrows | Most control. Good for layered architecture, request flows, data pipelines. | | Large auto-laid-out graphs | [D2](https://d2lang.com) or [Graphviz](https://graphviz.org), exported to SVG and pasted inline | Layout engines handle dozens of nodes better than hand placement. | | Sketchy whiteboard style | [Excalidraw](https://excalidraw.com), exported as SVG | Paste the SVG inline. | | Charts with data | Inline SVG, or a chart library from a CDN | Keep the data in the file. | For a polished, consistent house style for architecture and flow diagrams, the [diagram-design](https://github.com/cathrynlavery/diagram-design) skill is a good reference for agents. ## Make it look like your company Diagrams read best, and get shared more, when they look like the product they describe. Before drawing, find the brand and reuse it: - **In a repo**, look at the app itself: CSS variables or theme files, the Tailwind config, the fonts it loads, its logo. Use the same colors (a background, text, a muted tone, one or two accents), the same fonts from their CDN, and a light or dark look to match. - **In a chat**, ask once: “What does your product look like? A link to your site, your brand colors, or a screenshot is enough.” If there's nothing to go on, use a clean neutral style. - **Write it down** so every diagram matches: in a repo, `diagrams/brand.md` with the colors, fonts, and any logo URL. Each diagram still carries its styles inline (it can't load files from the repo), so copy them from there. ## Make it readable - **Say what it's for.** A title and a one-line subtitle ("How a checkout request reaches Stripe") at the top. - **Flow in one direction**, usually left to right or top to bottom. Number the steps if order matters. - **Label every arrow** with what moves along it (a request, an event, a file), not just that something connects. - **Group related parts** in labeled containers: services in a cluster, the browser vs. the server, your code vs. third parties. - **Few colors, used for meaning**: one accent for the thing the diagram is about, muted tones for the rest, and a small legend if color encodes something. - **Readable text**: 14px or larger, short labels, real names from the codebase (`OrderService`, `orders` table). - **Light and dark**: set a background color explicitly, or support both with `prefers-color-scheme`. - **Interactive when it helps**: hover to show details, click to expand a group. Keep it working without interaction. ## Keeping it current The diagram's source is the HTML file in the repo's `diagrams/` folder. To change a diagram, edit that file and push it again; the link stays the same and every version is kept. When the code it describes changes, ask the agent to update the diagram in the same change. --- # HTTP API reference Source: https://diagram.la/docs/api Every change on Diagram goes through this API or the MCP server, with the same keys and access checks. Use it from CI or scripts. - Base URL: `https://diagram.la/api/v1` - Auth: `Authorization: Bearer dgm_...` with a key from the [API keys](https://diagram.la/keys) page. - Bodies and responses are JSON. - `GET /api/v1` returns an index of the endpoints, and [`/openapi.json`](https://diagram.la/openapi.json) describes them in OpenAPI 3.1. ## Endpoints Who can read: the project's owner, the emails it added, and, for a project in an org with sharing on, everyone in the org. Orgs themselves are created and managed on the site. | Method | Path | Body | Who | | --- | --- | --- | --- | | GET | `/projects` | | Projects you own or were added to | | GET | `/orgs` | | Orgs you belong to | | POST | `/projects` | `{ slug, name?, org? }` | Anyone with a key | | GET | `/projects/:slug` | | Owner, members | | PATCH | `/projects/:slug` | `{ name?, org? }`. A new name moves the slug too (the old one keeps working and redirects); `org` is an org slug, or `null` for personal | Owner | | DELETE | `/projects/:slug` | Deletes the project and every diagram in it | Owner | | POST | `/projects/:slug/members` | `{ email }` | Owner | | DELETE | `/projects/:slug/members` | `{ email }` | Owner | | GET | `/projects/:slug/diagrams` | | Owner, members | | POST | `/projects/:slug/diagrams` | `{ title, html, visibility? }` | Owner | | GET | `/diagrams/:id` | `?html=1` also returns the HTML | Owner, members | | GET | `/<id>/screenshot` (site, not `/api`) | The current version as a JPEG, for whoever can open the diagram | Same as the diagram | | PUT / PATCH | `/diagrams/:id` | `{ html?, title?, visibility?, project? }` (`project` moves it to another project you own; same link) | Anyone who can see the project; `visibility` and `project`: owner | | GET | `/diagrams/:id/versions` | | Owner, members | | POST | `/diagrams/:id/restore` | `{ version }` publishes that version again as the newest | Anyone who can see the project | | DELETE | `/diagrams/:id` | | Owner | ## Examples Create a project and a diagram: ```sh curl -X POST https://diagram.la/api/v1/projects \ -H "Authorization: Bearer $DIAGRAM_API_KEY" -H 'content-type: application/json' \ -d '{"slug":"my-app","name":"My App"}' jq -Rs '{title:"Architecture", html:., visibility:"private"}' docs/architecture.html | curl -X POST https://diagram.la/api/v1/projects/my-app/diagrams \ -H "Authorization: Bearer $DIAGRAM_API_KEY" -H 'content-type: application/json' -d @- ``` The response includes the permanent link: ```json { "diagram": { "id": "Hk3pQ8zLw2Rt", "project": "my-app", "title": "Architecture", "visibility": "private", "version": 1, "url": "https://diagram.la/Hk3pQ8zLw2Rt", ... } } ``` Push a new version to the same link: ```sh jq -Rs '{html:.}' docs/architecture.html | curl -X PUT https://diagram.la/api/v1/diagrams/Hk3pQ8zLw2Rt \ -H "Authorization: Bearer $DIAGRAM_API_KEY" -H 'content-type: application/json' -d @- ``` The response is `{ diagram, changed }`. Identical HTML returns `changed: false` and doesn't add a version. Make it public: ```sh curl -X PATCH https://diagram.la/api/v1/diagrams/Hk3pQ8zLw2Rt \ -H "Authorization: Bearer $DIAGRAM_API_KEY" -H 'content-type: application/json' \ -d '{"visibility":"public"}' ``` ## Errors Errors are `{ "error": "message" }` with a status code: | Status | Meaning | | --- | --- | | 400 | The body failed validation. `issues` lists what's wrong. | | 401 | Missing, invalid, or revoked key. | | 403 | You can read the project but only its owner can change it, or you've hit an account limit. | | 404 | The project or diagram doesn't exist, or you can't see it. | | 409 | The project slug is taken. | ## Limits - 900KB of HTML per version. Every version is kept. - Free accounts own up to 5 projects of 100 diagrams each. Pro ($5/month) raises that to 100 projects of 1000 diagrams. See [pricing](/pricing). - 20 active API keys per account. - Project slugs are unique across the site: lowercase letters, digits, and dashes. --- # How diagrams are sandboxed Source: https://diagram.la/docs/security Diagram treats every diagram's HTML as untrusted, including your own. It's never rendered as part of a Diagram page. - `https://diagram.la/<id>` shows the diagram in an `<iframe>` with the `sandbox` attribute. - The frame loads `https://diagram.la/<id>/raw`, which is sent with a `Content-Security-Policy: sandbox` header, so it stays sandboxed even when opened directly. - The sandbox gives the diagram an opaque origin. Its scripts can't read Diagram's cookies, can't call the API as the viewer, and can't reach the page around it. ## What works inside a diagram - Inline `<script>` and `<style>`, and scripts, styles, fonts, and images loaded from other sites such as a CDN. - SVG, canvas, CSS animation, and click, hover, and zoom interactions. - Links that open in a new tab. ## What doesn't - Forms. Submitting them is blocked. - Cookies, `localStorage`, `sessionStorage`, and IndexedDB. Scripts that touch them will throw, so wrap that code in `try`/`catch`. - Top-level navigation, and framing the diagram from other sites. - Files next to the HTML in your repo. Inline them or load them from a URL. ## Accounts and keys - Sign-in is Google only. The session is an httpOnly cookie. - API keys are stored as SHA-256 hashes, shown once, and can be revoked on the [API keys](https://diagram.la/keys) page. Each key acts as the account that created it. - Only a project's owner can see and change it, plus the emails the owner adds as members, who can only read. Nobody else, including Diagram's own staff accounts, can list or open a private diagram. A public diagram opens for anyone with its exact link.