Skip to content

Generate a change diagram

lgtmaybe can post a C4-style diagram of what a pull request changes — the containers and components the PR touches plus their immediate relationships — so a reviewer gets a visual overview before they read the diff. It's a separate concern from the review and the description: enable any of them independently.

A /diagram comment posted by lgtmaybe: a C4 diagram of a Stripe webhook change, with the changed Checkout API and new Orders DB and Billing worker components highlighted with green borders

Contents

What you get

One model call returns two renderings of the same graph:

  • a Mermaid C4 diagram (C4Container / C4Context), which GitHub renders natively inside the comment — no image, no external hosting; and
  • a plain-text ASCII rendering of the same diagram, which is what shows in a terminal and serves as the fallback if the Mermaid can't be rendered.

Changed elements are marked in the labels ((new) / (changed)) and get a green border, so the PR's footprint stands out from the untouched collaborators at a glance; the relationship lines and labels are restyled in a light green that stays readable on every GitHub theme — Mermaid's C4 renderer defaults them to a near-black that disappears in dark mode — and the layout is loosened to three cards per row so the renderer's fixed-width cards don't overlap (a dense diagram of more than six elements drops further to two per row and grows down instead). Because GitHub's renderer offers zoom buttons but no full-screen, the diagram is followed by an ⛶ Open full screen link that renders the same diagram alone in a browser tab, with pan and zoom, on mermaid.live — the source travels compressed in the URL fragment, decoded in your browser, so nothing is sent anywhere until you click. The diagram also stays honest about the diff being only a slice of the codebase — relationships it infers from imports rather than the diff itself are called out in the notes rather than asserted as fact.

Here is what the posted comment looks like for a PR that puts a Redis cache in front of a user service — the Mermaid renders in place, with the ASCII tucked in a collapsible "Text version" underneath:

Cache user lookups in Redis

C4Container
    title User lookup after this change
    Person(client, "Client")
    Container(api, "User API", "Python", "Serves user reads")
    ContainerDb(cache, "Redis cache", "Redis", "caches user rows (new)")
    ContainerDb(db, "User DB", "Postgres")
    Rel(client, api, "GET /users/{id}")
    Rel(api, cache, "check cache (new)")
    Rel(api, db, "on miss, query")
    UpdateRelStyle(client, api, $textColor="#34a862", $lineColor="#34a862")
    UpdateRelStyle(api, cache, $textColor="#34a862", $lineColor="#34a862")
    UpdateRelStyle(api, db, $textColor="#34a862", $lineColor="#34a862")
    UpdateElementStyle(cache, $borderColor="#54d090")
    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

⛶ Open full screen  (the real link carries the diagram source compressed into the URL)

Text version 
[Client] --> [User API] --check--> [Redis cache] (new)
                  |
                  +--miss--> [User DB]

The User DB link is inferred from an import, not shown in the diff.

On GitHub: /diagram and auto_diagram

Comment /diagram on a pull request to post (or update in place) the change diagram. Like /describe, it's an idempotent upsert — re-running edits the same comment instead of stacking new ones.

auto_diagram is on by default — no workflow input or .lgtmaybe.yml needed — so a diagram posts automatically when a PR is opened or reopened. It never fires on a synchronize push. To opt out, set it in your workflow:

      - uses: MattJColes/lgtmaybe@v1
        with:
          provider: anthropic
          model: claude-sonnet-4-6
          auto_diagram: "false"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

or in .lgtmaybe.yml:

auto_diagram: false

The diagram is best-effort — a failure is logged and never blocks the review.

Locally: lgtmaybe diagram

lgtmaybe diagram prints a diagram of your local changes — no GitHub involved:

$ lgtmaybe diagram --provider ollama --model llama3

It diffs your branch against the base (the same base resolution as lgtmaybe review; --base overrides, --working includes uncommitted edits, --uncommitted reviews only the working-tree edits). The output is the same Markdown body the /diagram comment carries — the Mermaid source first, then the ASCII rendering (which reads fine in a terminal) in a collapsed "Text version" block. Paste the Mermaid into a GitHub comment, mermaid.live, or a Markdown file to render it.

Why Mermaid (and what the ASCII is for)

GitHub renders Mermaid natively in comments and Markdown, and Mermaid has a C4 dialect — so a mermaid fenced block renders in the comment with no image to generate or host. That matters for a pull_request_target reviewer: hosting an image would mean committing a file or calling an external service, neither of which fits a fork-safe, idempotently-updated comment.

A terminal, though, can't render Mermaid — which is exactly why the same call also returns ASCII art. Both the CLI output and the GitHub comment show the Mermaid with the ASCII tucked in a collapsible "Text version" — the ASCII is what you actually read in a terminal, and it doubles as the fallback body, so a reviewer never sees a red "unable to render" box if a diagram comes back malformed.

D2 (the C4 notation that inspired this) isn't used: GitHub doesn't render D2 in Markdown, so it would show as source anyway.

See also