{"slug": "show-hn-turn-every-pr-into-animated-architecture-diagrams-open-source", "title": "Show HN: Turn every PR into animated architecture diagrams (open-source)", "summary": "ColdTeaDotAI released PR Lens, an open-source tool that turns every pull request into animated architecture and data-flow diagrams posted inside the pull request, reducing cognitive load on AI-generated PRs. The tool offers five integration modes, including a hosted GitHub App, a coding-agent skill, a GitHub Action, and a CLI, all producing the same diagrams from a JSON document. The GitHub App posts one sticky comment per pull request and updates it on every push without requiring a model key, while the Action runs from CI with the user's own key, defaulting to Gemini.", "body_md": "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.\n\nThis 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.\n\nTwo 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.\n\nTip\n\n**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.\n\n```\nSet up PR Lens (prlens.dev) for me: it draws each pull request as animated architecture and data-flow diagrams, inside the pull request itself.\n\n1. Install the agent skill: `npx skills add coldteadotai/pr-lens`.\n\n2. 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.\n\n3. 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`.\n\n4. Then prove it: diagram the most recent change in this repository and show me the rendered SVGs.\n```\n\nNo 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.\n\nFive 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.\n\n**1. In your pull requests: the GitHub App** · hosted · live checkboxes · no key of yours\n\nInstall 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.\n\n**2. Via your coding agent** · it writes the document itself · no second model bill\n\nYour 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.\n\n```\nnpx skills add coldteadotai/pr-lens\n```\n\nThen say, literally:\n\nDiagram the change you just made with PR Lens and attach it to the pull request.\n\nThe agent reads the diff, writes the document, runs `npx @coldtea/pr-lens-cli validate`\n\nuntil the contract is satisfied, renders, and attaches the `<picture>`\n\npair. When someone says the diagram names things wrongly, the same skill teaches it to fix `.github/pr-lens.yml`\n\ninstead of editing generated output. Details in [ packages/agent-skill](/coldteadotai/pr-lens/blob/main/packages/agent-skill).\n\n**3. As a workflow: the GitHub Action** · your CI · your key · one static comment\n\nThe same comment from your own CI, drawn with your own model key. Add that key as a repository secret — `GEMINI_API_KEY`\n\nbelow, because `provider`\n\ndefaults to Gemini — then commit this as `.github/workflows/pr-lens.yml`\n\n:\n\n```\nname: PR Lens\n\non:\n  pull_request:\n\npermissions:\n  contents: write # to publish the rendered SVGs\n  pull-requests: write # to post the comment\n\nconcurrency: # one run per pull request; a push supersedes the last\n  group: pr-lens-${{ github.event.pull_request.number }}\n  cancel-in-progress: true\n\njobs:\n  lens:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0 # the diff is between two commits, so both must be here\n      - uses: coldteadotai/pr-lens/packages/action@v0\n        with:\n          api-key: ${{ secrets.GEMINI_API_KEY }}\n```\n\nNothing here is tied to one model. `provider`\n\ntakes `gemini`\n\n(the default), `openai`\n\n, or `openai-compatible`\n\nwith a `base-url`\n\nand `model`\n\n, 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).\n\n**4. From the CLI** · every step on your machine, one at a time\n\nEverything the other modes do, one step at a time, on your machine. Only `analyze`\n\ntalks to a model, and its key is read from the environment, never from a flag:\n\n```\nexport GEMINI_API_KEY=…    # the default provider; OPENAI_API_KEY with --provider openai\n\n# Diff in, graph document out — measured against the merge base, not the branch tip.\nnpx @coldtea/pr-lens-cli analyze --base origin/main\n\n# The document as light and dark SVGs, plus the manifest a comment is built from.\nnpx @coldtea/pr-lens-cli render .pr-lens/graph.json\n\n# The pull request comment as markdown, on stdout. Posting is your business.\nnpx @coldtea/pr-lens-cli comment --graph .pr-lens/drawn.graph.json --manifest .pr-lens/manifest.json \\\n  --asset-base-url https://raw.githubusercontent.com/owner/repo/pr-lens/42\n\n# Any PR Lens document, checked against the contract — every problem, not just the first.\nnpx @coldtea/pr-lens-cli validate .pr-lens/graph.json .github/pr-lens.yml\n\n# After the merge: the pull-request document as a stored map of the system, worth committing.\nnpx @coldtea/pr-lens-cli export .pr-lens/graph.json -o .github/pr-lens.map.json\n```\n\nEverything lands in `.pr-lens/`\n\n, which the CLI adds to your `.gitignore`\n\nthe 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`\n\nwrites. `--out`\n\nputs them somewhere else if you would rather.\n\nOllama, DeepSeek, OpenRouter and anything else speaking `/chat/completions`\n\nare reached with `--provider openai-compatible --base-url <url>`\n\n. 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).\n\n**5. In your terminal** · the diagram before the pull request exists\n\nNothing about the diagrams needs a pull request. Render locally and look at the change before anyone else does:\n\n```\nnpx @coldtea/pr-lens-cli analyze --base origin/main\nnpx @coldtea/pr-lens-cli render .pr-lens/graph.json\nopen .pr-lens/*-dark-*.svg    # macOS; the SVGs are self-contained, any browser reads them\n```\n\nThis 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.\n\nThe 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.\n\nThe smallest honest diagram: 1 lane · 1 node · 0 edges.\n\nThe dense synthetic: 3 lanes · 15 nodes · 19 edges. Crossings happen inside corridors and read as wiring, not spaghetti.\n\nCollapsed tiers dogfood the same <details> drill-down pattern the PR comment uses.\n\nThe 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.\n\nThe 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.\n\nEvery 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.\n\nEvery 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\n\n[teaser](/coldteadotai/pr-lens/blob/main/docs/showcase/teaser.ts), the\n\n[reference pull request](/coldteadotai/pr-lens/blob/main/packages/schema/src/examples/postmark-refactor.ts), the\n\n[dense synthetic](/coldteadotai/pr-lens/blob/main/packages/renderer/test/dense.ts), the\n\n[upper tiers](/coldteadotai/pr-lens/blob/main/packages/renderer/test/fixtures), the\n\n[mixed-kinds flow](/coldteadotai/pr-lens/blob/main/packages/renderer/test/mixed-kinds.ts). The comment mockups up top are framed by\n\n[around the same renders, with the composer's real text.](/coldteadotai/pr-lens/blob/main/docs/showcase/frame.ts)\n\n`docs/showcase/frame.ts`\n\n| Package | What it is |\n|---|---|\n`packages/schema` |\n\n`@coldtea/pr-lens-schema`\n\n: the contract every other component speaks`packages/renderer`\n\n`@coldtea/pr-lens-renderer`\n\n: deterministic JSON graph → the animated, theme-paired SVGs on this page`packages/cli`\n\n`@coldtea/pr-lens-cli`\n\n: read a diff with your own model key, render it, compose the comment`packages/action`\n\n`packages/agent-skill`\n\n`@coldtea/pr-lens-agent-skill`\n\n: teaches a coding agent to draw the change it just made\n\n```\npnpm install\npnpm verify      # build, typecheck, test\n```\n\nNode 20.11+ and pnpm 10.\n\nMIT © Coldtea AI.", "url": "https://wpnews.pro/news/show-hn-turn-every-pr-into-animated-architecture-diagrams-open-source", "canonical_source": "https://github.com/coldteadotai/pr-lens", "published_at": "2026-08-27 15:07:32+00:00", "updated_at": "2026-08-27 15:19:28.413233+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "generative-ai"], "entities": ["ColdTeaDotAI", "PR Lens", "GitHub App", "GitHub Action", "Gemini"], "alternates": {"html": "https://wpnews.pro/news/show-hn-turn-every-pr-into-animated-architecture-diagrams-open-source", "markdown": "https://wpnews.pro/news/show-hn-turn-every-pr-into-animated-architecture-diagrams-open-source.md", "text": "https://wpnews.pro/news/show-hn-turn-every-pr-into-animated-architecture-diagrams-open-source.txt", "jsonld": "https://wpnews.pro/news/show-hn-turn-every-pr-into-animated-architecture-diagrams-open-source.jsonld"}}