PR Lens: animated architecture diagrams inside the pull request

The review problem PR Lens is aimed at

A diff answers what changed line by line. It does not answer which components the change reaches, which calls now run between them, or what the request and response bodies look like after the edit. On a refactor that moves a queue behind a worker, the diff shows renamed symbols and moved files; the blast radius lives in the call graph, not in the hunks.

PR Lens targets that gap. The README states the goal directly: understand a pull request before you read a line of it. The audience is reviewers on a team where pull requests are large enough that reading the diff first is the wrong order of operations, and authors who want the shape of their change visible without writing an architecture document by hand.

The project is TypeScript, MIT licensed, and organised as a pnpm workspace with a packages/ directory, a skills/ directory for the coding-agent skill, and a root package.json that pins pnpm@10.5.2 and requires Node >=20.11. Recent releases are frequent: v0.5.0 on 2026-09-08, v0.6.0 on 2026-09-13, v0.6.1 on 2026-09-15, with the CLI and the agent skill versioned separately.

What the diagram actually contains

The comment is not a single picture. It nests <details> sections, each scoped to one part of the change: the whole blast radius on top, then the new path, then what was retired. The architecture view draws the components the pull request touches against the system around them, with the calls that run between them. Colour carries the delta, and the README fixes the mapping: green is new, amber is changed, red is gone.

The data-flow view is an ordered sequence. One dot crosses one arrow at a time, in the order the steps happen, so the reader watches the pipeline rather than reading it. Clicking any arrow opens a payload panel beside the graph with request and response, each as a declared shape or a sample body. The same colour rules apply inside the panel: new keys land green, dropped keys red.

Two details matter for how the comment behaves in practice. Every diagram ships as a light and dark pair when rendered through the GitHub App, and GitHub shows the one matching the reader's theme. And the comment links out to an interactive canvas with pan, zoom and a theme switch, which is where the walkthrough lives: it dims everything else, lights the cards and routes for one step, and prints a line describing what happened there. The README says play on the canvas, or press W. The canvas is the escape hatch for changes too wide to read inside a comment.

Installing the GitHub App and reading your first comment

The README leads with the GitHub App, which is the shortest path. You install it on a repository, open a pull request, and the diagram appears as a comment and is redrawn on every push. The README states the App is free for open source. No configuration file is documented for this path.

If you would rather render locally, the CLI is published on npm as @coldtea/pr-lens-cli and is invoked through npx:

npx @coldtea/pr-lens-cli

That runs the published CLI package. The README does not reproduce the flag list, so treat the CLI's own output as the reference rather than any flag you have seen quoted elsewhere.

For coding agents, the README gives a one-line skill install:

npx skills add coldteadotai/pr-lens

After that the agent can draw the diagram itself instead of waiting on the hosted App. The README also links a skill page at skills.sh/coldteadotai/pr-lens. What you should see in either path is the same visual grammar: lanes, node cards, delta colours, and routes you can trace by eye.

Where the output stops being useful

The README is candid about scale in one place. Next to the monorepo example, a six-lane graph with 37 nodes and 49 routed edges, it says: for what its worth, you should not be opening a PR this large. That is the honest boundary. The tool can render the graph, but a graph that size is evidence the pull request should have been split, not evidence the renderer is good.

The harder limitation is what the README does not document. There is no self-hosted server described, no configuration reference for the GitHub App, and no statement about how the tool derives the call graph from a diff. Whether it parses the TypeScript AST, reads an architecture file, or infers from imports is not stated in the README. That matters if your repository is polyglot: the project is TypeScript, and nothing in the README claims language coverage beyond what the examples show.

There is also a review-workflow cost. The diagram arrives as a bot comment, which means it sits in the same thread as human review. On a busy pull request with many pushes, a redrawn comment per push is another notification. Teams that treat bot comments as noise will not get value from this, however good the render is.

PR Lens against Mermaid and hand-written diagrams

The closest alternative is Mermaid, and the project positions itself against it explicitly through its topics, which include mermaid-alternative and diagrams-as-code. The difference in approach is who writes the diagram. With Mermaid you author the graph in a fenced code block and maintain it as the code changes; the diagram is a document you own, and it drifts the moment someone forgets to update it. PR Lens derives the diagram from the pull request and posts it, so the artefact is regenerated per change rather than maintained.

That trade cuts both ways. A Mermaid diagram can express anything you can describe, including intent the diff cannot show, and it renders anywhere a Markdown fence renders, with no App installation and no hosted service. PR Lens gives you less expressive control and more automatic coverage, plus the payload panel and the animated step-through, which a Mermaid sequence diagram does not have. If your team already keeps architecture-as-code files in the repository and reviews them, PR Lens is a second, overlapping source of truth. If your diagrams are stale or absent, the automatic path is the one that survives contact with a deadline.

Maintenance cost, licence and what to verify

The last push to main was on 2026-09-15, and the most recent release, v0.6.1, landed the same day, with the CLI at v0.6.1 and the agent skill at v0.3.0. The version numbers move independently, so pinning the CLI and the skill separately is the sane approach. The root package.json pins pnpm@10.5.2 for development and requires Node >=20.11, which is the version floor to check before wiring the CLI into CI.

The licence is MIT. In practical terms that permits commercial use and modification, and it requires the licence and copyright notice to be preserved; it does not grant trademark rights. This is a description of the licence text, not legal advice, and it is worth confirming against the LICENSE file in the repository before you redistribute anything.

The upgrade surface is the part to watch. Because the GitHub App renders on the hosted side, a change in the renderer version (v0.2.5 at the v0.6.0 release) can change the comment without any commit in your repository. The CLI and skill versions you pin locally will not protect you from that. If reproducible output matters, the CLI path is the one you control.

Editorial conclusion

Install the GitHub App on repositories where reviewers routinely face diffs they did not write, and keep the CLI for local rendering when you want a diagram before pushing. Skip it if your changes are single-file edits with no call graph to draw, or if your review process requires the diagram to be generated on infrastructure you control, since the README only documents the hosted GitHub App and a local CLI, not a self-hosted server. Before adopting, open one real pull request, confirm the comment renders the architecture view and the nested details sections, and check whether the payload panel shows the request and response shapes your team needs.

Frequently asked questions

Official sources

1. coldteadotai/pr-lens on GitHub
2. License: MIT
3. Project website
4. README
5. Releases