# Show HN: Turn every PR into animated architecture diagrams (open-source)

> Source: <https://github.com/coldteadotai/pr-lens>
> Published: 2026-08-27 15:07:32+00:00

Reduce the cognitive load on AI-generated PRs. PR Lens draws a pull request as animated diagrams **inside the pull request itself**: architecture blast radius and data-flow pipelines, not another findings table.

This is what lands in your pull request: a bot comment, drawn here card and all. Green is new, amber changed, red gone, and the pulse is the data moving along the new path.

Two lenses ship: **architecture** (what this change touches, against the existing system) and **data flow** (the ordered pipeline, animated). Every diagram on this page was rendered by this repo's renderer from a JSON document in this repo. This page *is* the product demo.

Tip

**Paste this into your coding agent.** It installs the skill, walks you through the GitHub App, and proves the setup by diagramming the last change in your repository.

```
Set up PR Lens (prlens.dev) for me: it draws each pull request as animated architecture and data-flow diagrams, inside the pull request itself.

1. Install the agent skill: `npx skills add coldteadotai/pr-lens`.

2. Walk me through installing the GitHub App at https://github.com/apps/coldtea-pr-lens on every repository where I review pull requests. It posts one sticky comment per pull request and updates it on every push, with no model key of mine involved.

3. If I'd rather run it from CI with a model key of mine, offer the Action instead: `.github/workflows/pr-lens.yml` using `coldteadotai/pr-lens/packages/action@v0`, with the key as a repository secret. It takes Gemini by default, OpenAI, or any endpoint speaking `/chat/completions`.

4. Then prove it: diagram the most recent change in this repository and show me the rendered SVGs.
```

No coding agent to hand? [ Install the PR Lens GitHub App](https://github.com/apps/coldtea-pr-lens) on its own, that gets every pull request the comment, with no key of yours involved.

Five ways in, the prompt above sets up the first two. Every mode produces the same diagrams from the same document; pick the one that matches where you review.

**1. In your pull requests: the GitHub App** · hosted · live checkboxes · no key of yours

Install the [PR Lens GitHub App](https://github.com/apps/coldtea-pr-lens) on your repository and open a pull request. That is the whole setup: every pull request gets the comment (the framed mockups at the top of this page are what lands), and each push updates it in place. This is the hosted mode, and the only one where the view-option checkboxes are live: tick one and the comment re-renders within seconds from the stored graph, no re-analysis, no key of yours involved.

**2. Via your coding agent** · it writes the document itself · no second model bill

Your agent is usually the model. Rather than spending a provider key to describe a diff it already understands, it writes the graph document itself and lets the validator hold it to the contract.

```
npx skills add coldteadotai/pr-lens
```

Then say, literally:

Diagram the change you just made with PR Lens and attach it to the pull request.

The agent reads the diff, writes the document, runs `npx @coldtea/pr-lens-cli validate`

until the contract is satisfied, renders, and attaches the `<picture>`

pair. When someone says the diagram names things wrongly, the same skill teaches it to fix `.github/pr-lens.yml`

instead of editing generated output. Details in [ packages/agent-skill](/coldteadotai/pr-lens/blob/main/packages/agent-skill).

**3. As a workflow: the GitHub Action** · your CI · your key · one static comment

The same comment from your own CI, drawn with your own model key. Add that key as a repository secret — `GEMINI_API_KEY`

below, because `provider`

defaults to Gemini — then commit this as `.github/workflows/pr-lens.yml`

:

```
name: PR Lens

on:
  pull_request:

permissions:
  contents: write # to publish the rendered SVGs
  pull-requests: write # to post the comment

concurrency: # one run per pull request; a push supersedes the last
  group: pr-lens-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  lens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # the diff is between two commits, so both must be here
      - uses: coldteadotai/pr-lens/packages/action@v0
        with:
          api-key: ${{ secrets.GEMINI_API_KEY }}
```

Nothing here is tied to one model. `provider`

takes `gemini`

(the default), `openai`

, or `openai-compatible`

with a `base-url`

and `model`

, so the same workflow runs against OpenRouter, DeepSeek or a server of your own. The key reaches the CLI through the environment, never a command line, and the diff goes to the provider you name and nowhere else. The comment here is deliberately static. An Action cannot hold state between runs, so the checkboxes live in the App. Providers, lenses, branding and the rest of the inputs are in [ packages/action](/coldteadotai/pr-lens/blob/main/packages/action).

**4. From the CLI** · every step on your machine, one at a time

Everything the other modes do, one step at a time, on your machine. Only `analyze`

talks to a model, and its key is read from the environment, never from a flag:

```
export GEMINI_API_KEY=…    # the default provider; OPENAI_API_KEY with --provider openai

# Diff in, graph document out — measured against the merge base, not the branch tip.
npx @coldtea/pr-lens-cli analyze --base origin/main

# The document as light and dark SVGs, plus the manifest a comment is built from.
npx @coldtea/pr-lens-cli render .pr-lens/graph.json

# The pull request comment as markdown, on stdout. Posting is your business.
npx @coldtea/pr-lens-cli comment --graph .pr-lens/drawn.graph.json --manifest .pr-lens/manifest.json \
  --asset-base-url https://raw.githubusercontent.com/owner/repo/pr-lens/42

# Any PR Lens document, checked against the contract — every problem, not just the first.
npx @coldtea/pr-lens-cli validate .pr-lens/graph.json .github/pr-lens.yml

# After the merge: the pull-request document as a stored map of the system, worth committing.
npx @coldtea/pr-lens-cli export .pr-lens/graph.json -o .github/pr-lens.map.json
```

Everything lands in `.pr-lens/`

, which the CLI adds to your `.gitignore`

the first time it writes there. Treat it as scratch: the files are rebuilt from the diff on demand, and the only one worth committing is the map `export`

writes. `--out`

puts them somewhere else if you would rather.

Ollama, DeepSeek, OpenRouter and anything else speaking `/chat/completions`

are reached with `--provider openai-compatible --base-url <url>`

. The full command reference, the correction file, and the failure codes a script can branch on are in [ packages/cli](/coldteadotai/pr-lens/blob/main/packages/cli).

**5. In your terminal** · the diagram before the pull request exists

Nothing about the diagrams needs a pull request. Render locally and look at the change before anyone else does:

```
npx @coldtea/pr-lens-cli analyze --base origin/main
npx @coldtea/pr-lens-cli render .pr-lens/graph.json
open .pr-lens/*-dark-*.svg    # macOS; the SVGs are self-contained, any browser reads them
```

This is also the shape of reviewing an agent's work: while you read the diff, the agent that wrote it renders it. With the skill installed, "render this change with PR Lens and open the SVGs" gets you the diagram beside the diff, the same picture its pull request will carry, minutes earlier.

The renderer answers for every size of change with the same visual grammar: lanes, node cards, delta colours, and routes you can trace with the eye alone.

The smallest honest diagram: 1 lane · 1 node · 0 edges.

The dense synthetic: 3 lanes · 15 nodes · 19 edges. Crossings happen inside corridors and read as wiring, not spaghetti.

Collapsed tiers dogfood the same <details> drill-down pattern the PR comment uses.

The ordered pipeline of the change, drawn in the same design system: participants are real node cards, labels are the same pills, colours are the same deltas. **The pulses are moving right now**: PR Lens diagrams are animated SVG, and the animation survives GitHub's image proxy, a hook no findings table has.

The reference pull request's send pipeline: 7 steps sharing one cycle and taking it in turn. One dot crosses one arrow at a time, in the order the steps happen, and the next arrow lights as the last dot lands.

Every message kind at once: a filled head waits for an answer, an open head is fire-and-forget, a dashed line is the answer, and only waited-on work lights an activation bar.

Every render above comes from a checked-in fixture, regenerated deterministically by [ docs/showcase/render.mts](/coldteadotai/pr-lens/blob/main/docs/showcase/render.mts): the

[teaser](/coldteadotai/pr-lens/blob/main/docs/showcase/teaser.ts), the

[reference pull request](/coldteadotai/pr-lens/blob/main/packages/schema/src/examples/postmark-refactor.ts), the

[dense synthetic](/coldteadotai/pr-lens/blob/main/packages/renderer/test/dense.ts), the

[upper tiers](/coldteadotai/pr-lens/blob/main/packages/renderer/test/fixtures), the

[mixed-kinds flow](/coldteadotai/pr-lens/blob/main/packages/renderer/test/mixed-kinds.ts). The comment mockups up top are framed by

[around the same renders, with the composer's real text.](/coldteadotai/pr-lens/blob/main/docs/showcase/frame.ts)

`docs/showcase/frame.ts`

| Package | What it is |
|---|---|
`packages/schema` |

`@coldtea/pr-lens-schema`

: the contract every other component speaks`packages/renderer`

`@coldtea/pr-lens-renderer`

: deterministic JSON graph → the animated, theme-paired SVGs on this page`packages/cli`

`@coldtea/pr-lens-cli`

: read a diff with your own model key, render it, compose the comment`packages/action`

`packages/agent-skill`

`@coldtea/pr-lens-agent-skill`

: teaches a coding agent to draw the change it just made

```
pnpm install
pnpm verify      # build, typecheck, test
```

Node 20.11+ and pnpm 10.

MIT © Coldtea AI.