Diagram
← Developer reference

Repo setup and CI

Let Claude Code, Codex, Cursor, or any coding agent draw diagrams for your repo, save them to Diagram at stable links over MCP, and publish them when you say so.

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 to Diagram where only you can see it, and hands you a link. Each change it makes is saved to the same link, and the page you have open updates by itself. In a project your team shares, a new diagram is a draft until you tell it to publish. Nothing lives only in a local file, so there's nothing to forget to upload.

Connect the agent

Sign in and open Get started (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.

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/README.md, which tells agents which project this repo uses and how to draw, save, and publish (below), next to a diagrams/brand.md the agent writes so diagrams match your product.
  • 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. Commit the folder.

Diagrams themselves live on Diagram, not in the repo. If you want copies versioned with your code, ask the agent to keep them: it writes each one to diagrams/<name>.html with its diagram id in a <meta name="diagram-id"> tag. The copy is a snapshot; Diagram stays the source of truth.

The section added to CLAUDE.md / AGENTS.md:

<!-- diagram -->
## Diagrams

This repo's diagrams are on Diagram, project `my-app`. Before drawing or changing one, read `diagrams/README.md` and follow it.
<!-- /diagram -->

diagrams/README.md:

<!-- diagram:readme — written by Diagram setup; ask your agent to set up Diagram again to refresh -->
# Diagrams

This repo's diagrams are on Diagram, in the project `my-app`: https://diagram.la/p/my-app

## For agents

Diagrams for this repo live on Diagram, not in this folder: every one is saved there as you work, so nothing is ever only on one computer. Use the Diagram MCP tools. 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; for other tools, https://diagram.la/start

1. **New diagram.** Draw it as one self-contained HTML document and call `save_diagram` with `project: "my-app"`. If anyone else can see the project, it starts as a draft only you and the project's owner can see (the save result says). Give the user the link right away; the page they open updates by itself as you save.
2. **Changes.** Call `edit_diagram` with the diagram's id and the exact pieces of HTML to replace. It's much faster than sending the whole document. If you don't have the current HTML, read it with `get_diagram` first (it returns an outline; `find` returns the HTML around a piece of text), so you never undo someone else's change. Find diagrams with `list_diagrams`.
3. **Save after every change the user asks for.** Don't keep work in a local file: it isn't shared, or safe, until it's saved to Diagram.
4. **Publish drafts when they say so.** When the user is happy with a draft, ask whether to publish it and say who will then see it (the save result tells you). Call `publish_diagram` only after they say yes.
5. **Everything inline.** CSS, JS, and SVG go in the document. Scripts from a CDN such as jsDelivr are fine (for example 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 files from the repo, use cookies or localStorage, or submit forms.
6. **Add a `<title>`.** It becomes the diagram's title and the text in link previews.
7. **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`. Guide: https://diagram.la/docs/drawing
8. **Keep it small and readable.** Under 900KB. Draw with inline SVG, HTML/CSS or a library rather than embedded images. First choose the kind of diagram that best shows what was asked (a timeline, Gantt chart, sequence, state machine, tree, comparison, chart, exploded view, flowchart…), not boxes and arrows by default. Give it a title and subtitle; when it has arrows, flow in one direction and label each one.
9. **Copies in the repo are optional.** Only if the user asks to keep diagrams with the code: after saving, write the same HTML to `diagrams/<name>.html` with `<meta name="diagram-id" content="<its id>">` in the `<head>`. The copy is a snapshot; Diagram stays the source of truth, so always load the current HTML from Diagram before changing it.
10. **Sharing beyond the project is web-only.** To make a diagram public or add people, give the user its link and tell them to change it on the Diagram site.
11. **No keys in the repo.** The Diagram connection lives in the AI tool's MCP settings.

What a good diagram looks like

  • One HTML document 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).

Mermaid, D2, Graphviz, Excalidraw exports, hand-written SVG, and plain HTML with CSS all work. The Mermaid guide has a template.

This is for teams that keep copies in the repo (above) and edit them there. CI can't use MCP, so it publishes over the HTTP API. Each file's diagram-id tag says which diagram it is, so CI updates the same links. Add an API key as a repository secret and publish changed diagrams on every merge. For GitHub Actions:

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. See the API reference for curl examples.