Features
Not Mermaid, better
We built a custom renderer from scratch. It draws rich animated visuals, reduces cognitive overload, represents code additions, removals and changes and still works for representing very large systems
Architecture blast radius
The diagram shows the parts of your system that the code change touches, drawn against the system around it: the components involved, and the calls that run between them.
Colors show what changed: green is new, amber is changed, and red is removed.
Intuitive Data flow
Understand how data flows through your any code change or codebase. The diagram plays the steps of the change in order with a moving dot one step at a time
See the payload on every data flow
Click any arrow to see the data it carries. A panel opens next to the diagram with the request and the response. Each one shows either the expected shape or a sample. New fields are green and removed fields are red, the same colors the diagram uses.
Zoom in without leaving the page
The comment has folding sections (<details>) that you can open and close. Each one has its own diagram for one part of the change. The whole change is on top. Below it is the new path, and then what was removed.
Interactive canvas
Every comment or drawing can link to an interactive canvas. It has the same diagrams at full size. You can move around, zoom, and switch between a light and a dark theme. A big change gets all the room it needs instead of squeezing into a narrow comment or static image.
Walk through the change
PR Lens ships with animated explainers called walkthroughs. Walkthroughs let you explore a system or code change step by step, without overwhelm. Start a walkthrough by pressing play on the canvas, or press W.
Your agent, live on the canvas
Ask your local coding agent to connect to a canvas. Then use it to understand any codebase or code change. You can ask follow-up questions, zoom into any part of the diagram, or drag across a few cards and ask your agent about them. Watch it interact live with the canvas!
From one card to a whole monorepo
Every size of change uses the same look: lanes, cards, colors for what changed, and paths you can follow with your eyes.
For what it's worth, you should not open a pull request this big.
Light or dark theme
With the GitHub App, every diagram comes in a light and a dark version. GitHub shows the one that matches the reader's theme. You can also draw either theme on your own computer with your coding agent.
GitHub, GitLab and Bitbucket
PR Lens works on all three. On GitHub, install the App. On GitLab, add the CI/CD component to your pipeline. On Bitbucket, add the pipe.
Set it up for GitLab or Bitbucket
Hall of Fame
We ran the pull requests behind React Hooks, Node fetch and Kubernetes Ingress through PR Lens. They were drawn with the same renderer and the same format as the diagrams above.
react/react#13968 · 36 files · +5,868/−130 · 5 lanes. Hooks are added behind a feature flag.
nodejs/node#41749 · 16 files · +8,076/−3 · 5 lanes. fetch, Request, Response and Headers are added to Node itself.
kubernetes/kubernetes#14175 · 8 files · +766/−0 · 4 lanes. The first Ingress type, for L7 load balancing.
vuejs/core#2532 · 11 files · +1,081/−670 · 3 lanes. <script setup> and the first version of ref sugar.
rust-lang/rust#31954 · 26 files · +369/−16 · 4 lanes. The ? operator, a short way to write try! that you can chain.
tokio-rs/tokio#1657 · 100 files · +7,408/−6,795 · 3 lanes. The work-stealing pool, rebuilt so the scheduler does less extra work.
neovim/neovim#11336 · 15 files · +5,556/−1 · 3 lanes. The LSP client moves into Neovim itself.
django/django#11209 · 38 files · +931/−42 · 5 lanes. An ASGI handler, and a request context that is safe to use with coroutines.
webpack/webpack#10440 · 13 files · +567/−5 · 5 lanes. ContainerPlugin, which brought module federation with it.
vllm-project/vllm#1348 · 6 files · +764/−139 · 3 lanes. PagedAttention V2 and its sequence-level parallelism.
Open the Hall of Fame. Every diagram there is live.
Configuration
Add a .github/pr-lens.yml file to change how PR Lens works. GitLab and Bitbucket have no .github/ folder, so there you can use .gitlab/pr-lens.yml or a pr-lens.yml at the top of the repo. They work the same way. The configuration reference lists every setting, its default, and examples.
Fix names and mistakes
When you draw with the CLI, put your fixes in .github/pr-lens.yml. Don't edit the SVG files it makes:
schemaVersion: 0.1.0
map:
rename:
- match: services/legacy-mailer.ts
to: Postmark sender
exclude:
- "**/*.test.ts"
These fixes sit on top of what the model finds. They keep working as the code changes, even when the model names things differently from one run to the next. You can rename things, leave files out, pin cards to a lane, and group things together. See packages/cli for all of it.
Other ways to run it
For most people, the App is all they need. The options below cover what it doesn't: your own CI, your own model, or a diagram before the pull request exists.
A lot happens before a pull request is opened. Your agent can use the same renderer to help you understand any codebase or check its own changes before there is a pull request. It also helps you keep a clear picture of your system as it grows.
npx skills add coldteadotai/pr-lens
Then ask your coding agent something like:
Diagram the change you just made with PR Lens and attach it to the pull request.
The agent reads the diff and writes the diagram file. It runs npx @coldtea/pr-lens-cli validate until the file passes every check. Then it draws the diagram and adds it to the pull request description with gh pr create --attach, so the diagram is there as soon as the pull request opens. If a diagram gets a name wrong, the skill teaches the agent to fix .github/pr-lens.yml instead of editing the files it made. See packages/agent-skill for more.
Want the agent to do the whole setup? Paste this:
Set up PR Lens for me. It draws code changes as moving diagrams of the system and how data flows through it.
1. Install the agent skill: `npx skills add coldteadotai/pr-lens`.
2. Help me install the GitHub App at https://github.com/apps/coldtea-pr-lens on every repository where I review pull requests. It posts one comment per pull request and updates that comment on every push. It does not need a model key from me.
3. If I'd rather run it from CI with my own model key, offer the Action instead: `.github/workflows/pr-lens.yml` using `coldteadotai/pr-lens/packages/action@v0`, with the key saved as a repository secret. It works with any service that speaks `/chat/completions`, such as OpenAI or Gemini.
4. Then test it: diagram the latest change in this repository and show me the SVGs or the canvas.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
