Skip to content
Back to search

pr-lens

Review code 100X faster. Lens draws every PR as animated architecture and data-flow walkthroughs, inside the pull request itself. Use it as a GitHub App, GitHub Action, CLI, or a Skill for your coding agent

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/coldteadotai/pr-lens with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/coldteadotai/pr-lens'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/coldteadotai-pr-lens/badge.svg)](/listings/coldteadotai-pr-lens)

HTML

<a href="/listings/coldteadotai-pr-lens"><img src="/api/listings/coldteadotai-pr-lens/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 552 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="docs/brand/mark.dark.svg">
  4. <img alt="" src="docs/brand/mark.light.svg" width="76">
  5. </picture>
  6. </p>
  7. <h1 align="center">PR Lens</h1>
  8. <p align="center">English · <a href="README.zh-CN.md">简体中文</a></p>
  9. <p align="center">
  10. <b>Understand a pull request, any codebase, or software visually, before you read a line of code</b><br>
  11. PR Lens maps the architecture and data flow of every pull request,<br>
  12. inside the pull request itself, and flags what could break.<br>
  13. Open it on a live canvas for a guided tour, or let your coding agent walk you through any codebase
  14. </p>
  15. <p align="center">
  16. <a href="https://github.com/apps/coldtea-pr-lens"><img alt="Install the GitHub App" src="https://img.shields.io/badge/GitHub%20App-install-3fb950?style=flat-square&logo=github&logoColor=white&labelColor=21262d"></a>
  17. <a href="https://www.npmjs.com/package/@coldtea/pr-lens-cli"><img alt="The CLI on npm" src="https://img.shields.io/npm/v/%40coldtea%2Fpr-lens-cli?style=flat-square&logo=npm&logoColor=white&label=cli&labelColor=21262d&color=21262d"></a>
  18. <a href="https://discord.gg/nTEFnmBQMJ"><img alt="Join the Discord" src="https://img.shields.io/badge/Discord-join-5865F2?style=flat-square&logo=discord&logoColor=white&labelColor=21262d"></a>
  19. <a href="https://prlens.dev"><img alt="prlens.dev" src="https://img.shields.io/badge/website-prlens.dev-21262d?style=flat-square&labelColor=21262d"></a>
  20. <a href="LICENSE"><img alt="MIT licence" src="https://img.shields.io/github/license/coldteadotai/pr-lens?style=flat-square&labelColor=21262d&color=21262d"></a>
  21. </p>
  22. <h3 align="center"><a href="https://github.com/apps/coldtea-pr-lens">Install the GitHub App</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://skills.sh/coldteadotai/pr-lens">Install the Skill</a></h3>
  23. <p align="center">
  24. <sub>Also runs on <a href="https://prlens.dev/gitlab">GitLab</a> and <a href="https://prlens.dev/bitbucket">Bitbucket</a></sub>
  25. </p>
  26. <p align="center">
  27. <sub>Free for open source &nbsp;&nbsp;·&nbsp;&nbsp; Or have your coding agent map it: <code>npx skills add coldteadotai/pr-lens</code></sub>
  28. </p>
  29. <p align="center">
  30. <picture>
  31. <source media="(prefers-color-scheme: dark)" srcset="docs/brand/cta-strip.dark.svg">
  32. <img alt="Three steps: install the GitHub App on any repository, open a pull request, and read the map, which updates on every push" src="docs/brand/cta-strip.light.svg" width="960">
  33. </picture>
  34. </p>
  35. <picture>
  36. <source media="(prefers-color-scheme: dark)" srcset="docs/showcase/teaser.comment.dark.svg">
  37. <img alt="A PR Lens comment in a pull request: small labels with numbers about the change, a diagram of a small change, and checkboxes to pick other views" src="docs/showcase/teaser.comment.light.svg">
  38. </picture>
  39. <br />
  40. ## Features
  41. <table>
  42. <tr>
  43. <td width="46%" valign="middle">
  44. ### Not Mermaid, better
  45. We built a custom renderer from scratch. It renders rich visuals, reduces cognitive overload, represents code additions, removals and changes and still works for representing very large systems
  46. </td>
  47. <td width="54%" valign="middle">
  48. <img alt="A code diff with a round lens moving over it. Inside the lens, the same change shows up as PR Lens cards and the paths between them" src="docs/showcase/welcome.not-mermaid.gif">
  49. </td>
  50. </tr>
  51. <tr>
  52. <td width="46%" valign="middle">
  53. ### Architecture blast radius
  54. The map shows the parts of your system that the code change touches, set against the system around it: the components involved, and the calls that run between them.
  55. Colors show what changed: **green** is new, **amber** is changed, and **red** is removed.
  56. </td>
  57. <td width="54%" valign="middle">
  58. <picture>
  59. <source media="(prefers-color-scheme: dark)" srcset="docs/showcase/tier2-reference.architecture.dark.svg">
  60. <img alt="A diagram of a real change that reorganizes code: three lanes and ten parts, with the changed ones shown in color" src="docs/showcase/tier2-reference.architecture.light.svg">
  61. </picture>
  62. </td>
  63. </tr>
  64. <tr>
  65. <td width="46%" valign="middle">
  66. ### Intuitive Data flow
  67. Understand how data flows through any code change or codebase. The map plays the steps of the change in order, with a moving dot, one step at a time. Animation is usually a distraction. Here it is intentional.
  68. </td>
  69. <td width="54%" valign="middle">
  70. <picture>
  71. <source media="(prefers-color-scheme: dark)" srcset="docs/showcase/reference.data-flow.dark.svg">
  72. <img alt="A moving step-by-step diagram: seven steps, each taking its turn" src="docs/showcase/reference.data-flow.light.svg">
  73. </picture>
  74. </td>
  75. </tr>
  76. <tr>
  77. <td width="46%" valign="middle">
  78. ### See the payload on every data flow
  79. Click any arrow to see the data it carries. A panel opens next to the map 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 map uses.
  80. </td>
  81. <td width="54%" valign="middle">
  82. <img alt="Clicking the enqueue broadcast job arrow: a side panel opens with the request body. Added fields are green and a removed field is red. Then the Response tab opens and shows the expected shape" src="docs/showcase/welcome.payload.gif">
  83. </td>
  84. </tr>
  85. <tr>
  86. <td width="46%" valign="middle">
  87. ### What could break?
  88. PR Lens also reviews the change. It flags bugs, security holes and design problems in the same comment, with a fix for each and a prompt you can hand to your coding agent.
  89. On GitHub, each finding also goes on the line of the diff it's about, and PR Lens checks it again on every push.
  90. <sub>Only in the hosted app, on GitHub, GitLab and Bitbucket. Every other way to run PR Lens (the Action, the CI component, the pipe, the CLI and the skill) gives you the map without the review.</sub>
  91. </td>
  92. <td width="54%" valign="middle">
  93. <img alt="A PR Lens finding in the pull request comment: a high-severity security problem, what could go wrong, the fix, and a prompt for AI agents" src="docs/showcase/finding.comment.png">
  94. </td>
  95. </tr>
  96. <tr>
  97. <td width="46%" valign="middle">
  98. ### Zoom in without leaving the page
  99. The comment has folding sections (`<details>`) that you can open and close. Each one has its own map for one part of the change. The whole change is on top. Below it is the new path, and then what was removed.
  100. </td>
  101. <td width="54%" valign="middle">
  102. <picture>
  103. <source media="(prefers-color-scheme: dark)" srcset="docs/showcase/reference.new-batch-path.dark.svg">
  104. <img alt="The same pull request zoomed into one section: two lanes, showing only the new batch path" src="docs/showcase/reference.new-batch-path.light.svg">
  105. </picture>
  106. </td>
  107. </tr>
  108. <tr>
  109. <td width="46%" valign="middle">
  110. ### Interactive canvas
  111. Every comment or map can link to an interactive canvas. It has the same maps 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.
  112. </td>
  113. <td width="54%" valign="middle">
  114. <a href="https://prlens.dev/c/uSdxMcPBFwhfgfaGh-dveQ"><img alt="The canvas: zooming into a small diagram, switching to the light theme, then fitting it back to the screen" src="docs/showcase/welcome.canvas.gif"></a>
  115. </td>
  116. </tr>
  117. <tr>
  118. <td width="46%" valign="middle">
  119. ### Walk through the change
  120. Every map comes with a guided tour of the change, called a walkthrough. 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.
  121. </td>
  122. <td width="54%" valign="middle">
  123. <a href="https://prlens.dev/c/uSdxMcPBFwhfgfaGh-dveQ"><img alt="A walkthrough on the canvas: the first step lights up the signup route and the new queue. The second step zooms in on the queue and the worker that empties it" src="docs/showcase/welcome.walkthrough.gif"></a>
  124. </td>
  125. </tr>
  126. <tr>
  127. <td width="46%" valign="middle">
  128. ### Ask your agent, and watch it show you
  129. 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 map, or drag across a few cards and ask your agent about them. Watch it interact live with the canvas!
  130. </td>
  131. <td width="54%" valign="middle">
  132. <img alt="A coding agent in a terminal next to a live canvas. A question typed in the terminal comes back on the canvas as a two-step answer, and the canvas follows the agent through each step" src="docs/showcase/welcome.live.gif">
  133. </td>
  134. </tr>
  135. <tr>
  136. <td width="46%" valign="middle">
  137. ### From one card to a whole monorepo
  138. Every size of change uses the same look: lanes, cards, colors for what changed, and paths you can follow with your eyes.
  139. For what it's worth, you should not open a pull request this big.
  140. </td>
  141. <td width="54%" valign="middle">
  142. <picture>
  143. <source media="(prefers-color-scheme: dark)" srcset="docs/showcase/tier5-monorepo.architecture.dark.svg">
  144. <img alt="A monorepo diagram with six lanes, 37 cards and 49 connecting lines" src="docs/showcase/tier5-monorepo.architecture.light.svg">
  145. </picture>
  146. </td>
  147. </tr>
  148. <tr>
  149. <td width="46%" valign="middle">
  150. ### Light or dark theme
  151. With the GitHub App, every map comes in a light and a dark version. GitHub shows the one that matches the reader's theme. You can also render either theme on your own computer with your coding agent.
  152. </td>
  153. <td width="54%" valign="middle">
  154. <p align="center"><img alt="One small diagram cut on a slant: the dark theme on the left and the light theme on the right. Every card and path lines up across the cut" src="docs/showcase/welcome.architecture.split.svg" width="487"></p>
  155. </td>
  156. </tr>
  157. <tr>
  158. <td width="46%" valign="middle">
  159. ### GitHub, GitLab and Bitbucket
  160. 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.
  161. Set it up for [GitLab](https://prlens.dev/gitlab) or [Bitbucket](https://prlens.dev/bitbucket)
  162. </td>
  163. <td width="54%" valign="middle">
  164. <p align="center">
  165. <picture>
  166. <source media="(prefers-color-scheme: dark)" srcset="docs/brand/forges.dark.svg">
  167. <img alt="GitHub, GitLab and Bitbucket" src="docs/brand/forges.light.svg" width="360">
  168. </picture>
  169. </p>
  170. </td>
  171. </tr>
  172. </table>
  173. <br />
  174. ## Hall of Fame
  175. We ran the pull requests behind React Hooks, Node fetch and Kubernetes Ingress through PR Lens. They were mapped with the same renderer and the same format as the maps above.
  176. <a href="https://prlens.dev/gallery/react/react/13968"><img alt="React Hooks, drawn again: four lanes across the React package, the reconciler, the server renderer and shared config" src="docs/showcase/gallery/react-hooks.svg"></a>
  177. <sub><b><a href="https://prlens.dev/gallery/react/react/13968">react/react#13968</a></b> · 36 files · +5,868/−130 · 5 lanes. Hooks are added behind a feature flag.</sub>
  178. <a href="https://prlens.dev/gallery/nodejs/node/41749"><img alt="Node's fetch code, drawn again across five lanes" src="docs/showcase/gallery/node-fetch.svg"></a>
  179. <sub><b><a href="https://prlens.dev/gallery/nodejs/node/41749">nodejs/node#41749</a></b> · 16 files · +8,076/−3 · 5 lanes. `fetch`, `Request`, `Response` and `Headers` are added to Node itself.</sub>
  180. <a href="https://prlens.dev/gallery/kubernetes/kubernetes/14175"><img alt="The first Kubernetes Ingress type, drawn again across four lanes" src="docs/showcase/gallery/kubernetes-ingress.svg"></a>
  181. <sub><b><a href="https://prlens.dev/gallery/kubernetes/kubernetes/14175">kubernetes/kubernetes#14175</a></b> · 8 files · +766/−0 · 4 lanes. The first Ingress type, for L7 load balancing.</sub>
  182. <details>
  183. <summary><b>Seven more</b> · Vue, Rust, Tokio, Neovim, Django, webpack, vLLM</summary>
  184. <br>
  185. <a href="https://prlens.dev/gallery/vuejs/core/2532"><img alt="Vue's script setup and ref sugar, drawn again across three lanes" src="docs/showcase/gallery/vue-script-setup.svg"></a>
  186. <sub><b>vuejs/core#2532</b> · 11 files · +1,081/−670 · 3 lanes. `&lt;script setup&gt;` and the first version of ref sugar.</sub>
  187. <a href="https://prlens.dev/gallery/rust-lang/rust/31954"><img alt="Rust's question mark operator, drawn again across four lanes" src="docs/showcase/gallery/rust-try-operator.svg"></a>
  188. <sub><b>rust-lang/rust#31954</b> · 26 files · +369/−16 · 4 lanes. The `?` operator, a short way to write `try!` that you can chain.</sub>
  189. <a href="https://prlens.dev/gallery/tokio-rs/tokio/1657"><img alt="Tokio's rewritten work-stealing thread pool, drawn again across three lanes" src="docs/showcase/gallery/tokio-work-stealing.svg"></a>
  190. <sub><b>tokio-rs/tokio#1657</b> · 100 files · +7,408/−6,795 · 3 lanes. The work-stealing pool, rebuilt so the scheduler does less extra work.</sub>
  191. <a href="https://prlens.dev/gallery/neovim/neovim/11336"><img alt="Neovim's built-in LSP client, drawn again across three lanes" src="docs/showcase/gallery/neovim-lsp.svg"></a>
  192. <sub><b>neovim/neovim#11336</b> · 15 files · +5,556/−1 · 3 lanes. The LSP client moves into Neovim itself.</sub>
  193. <a href="https://prlens.dev/gallery/django/django/11209"><img alt="Django's ASGI handler, drawn again across five lanes" src="docs/showcase/gallery/django-asgi.svg"></a>
  194. <sub><b>django/django#11209</b> · 38 files · +931/−42 · 5 lanes. An ASGI handler, and a request context that is safe to use with coroutines.</sub>
  195. <a href="https://prlens.dev/gallery/webpack/webpack/10440"><img alt="Webpack's ContainerPlugin, drawn again across five lanes" src="docs/showcase/gallery/webpack-federation.svg"></a>
  196. <sub><b>webpack/webpack#10440</b> · 13 files · +567/−5 · 5 lanes. `ContainerPlugin`, which brought module federation with it.</sub>
  197. <a href="https://prlens.dev/gallery/vllm-project/vllm/1348"><img alt="vLLM's PagedAttention V2, drawn again across three lanes" src="docs/showcase/gallery/vllm-paged-attention.svg"></a>
  198. <sub><b>vllm-project/vllm#1348</b> · 6 files · +764/−139 · 3 lanes. PagedAttention V2 and its sequence-level parallelism.</sub>
  199. </details>
  200. <b><a href="https://prlens.dev/gallery">Open the Hall of Fame</a></b>. Every map there is live.
  201. <br />
  202. ## Configuration
  203. 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](packages/schema#repository-config) lists every setting, its default, and examples.
  204. ### Fix names and mistakes
  205. When you map a change with the CLI, put your fixes in `.github/pr-lens.yml`. Don't edit the SVG files it makes:
  206. ```yaml
  207. schemaVersion: 0.1.0
  208. map:
  209. rename:
  210. - match: services/legacy-mailer.ts
  211. to: Postmark sender
  212. exclude:
  213. - "**/*.test.ts"
  214. ```
  215. 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`](packages/cli#corrections) for all of it.
  216. <br />
  217. ## Other ways to run it
  218. 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 map before the pull request exists.
  219. <details open>
  220. <summary><b>Via your coding agent</b></summary>
  221. <br>
  222. 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.
  223. <p align="center">
  224. <picture>
  225. <source media="(prefers-color-scheme: dark)" srcset="docs/brand/agents.dark.svg">
  226. <img alt="Claude Code, Codex, Gemini CLI, Cursor, OpenCode and Copilot" src="docs/brand/agents.light.svg" width="720">
  227. </picture>
  228. <br>
  229. </p>
  230. ```bash
  231. npx skills add coldteadotai/pr-lens
  232. ```
  233. Then ask your coding agent something like:
  234. > Map the change you just made with PR Lens and attach it to the pull request.
  235. The agent reads the diff and writes the map file. It runs `npx @coldtea/pr-lens-cli validate` until the file passes every check. Then it renders the map and adds it to the pull request description with `gh pr create --attach`, so the map is there as soon as the pull request opens. If a map 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`](packages/agent-skill) for more.
  236. Want the agent to do the whole setup? Paste this:
  237. ```text
  238. Set up PR Lens for me. It maps how code changes touch the system and how data flows through it.
  239. 1. Install the agent skill: `npx skills add coldteadotai/pr-lens`.
  240. 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.
  241. 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.
  242. 4. Then test it: map the latest change in this repository and show me the SVGs or the canvas.
  243. ```
  244. </details>
  245. <details>
  246. <summary><b>As a workflow: the GitHub Action</b> · your CI · your key · one comment that stays the same</summary>
  247. <br>
  248. This posts the same comment from your own CI, mapped with your own model key. Save the key as a repository secret. The example below uses `GEMINI_API_KEY` because `provider` is Gemini by default. Then commit this file as `.github/workflows/pr-lens.yml`:
  249. ```yaml
  250. name: PR Lens
  251. on:
  252. pull_request:
  253. permissions:
  254. contents: write # to publish the rendered SVGs
  255. pull-requests: write # to post the comment
  256. concurrency: # one run per pull request; a push supersedes the last
  257. group: pr-lens-${{ github.event.pull_request.number }}
  258. cancel-in-progress: true
  259. jobs:
  260. lens:
  261. runs-on: ubuntu-latest
  262. steps:
  263. - uses: actions/checkout@v4
  264. with:
  265. fetch-depth: 0 # the diff is between two commits, so both must be here
  266. - uses: coldteadotai/pr-lens/packages/action@v0
  267. with:
  268. api-key: ${{ secrets.GEMINI_API_KEY }}
  269. ```
  270. You can use any model. `provider` can be `gemini` (the default), `openai`, or `openai-compatible` with a `base-url` and `model`. So the same workflow works with OpenRouter, DeepSeek or your own server. The key reaches the CLI through the environment, never on a command line. The diff goes only to the provider you pick. This comment stays the same after it is posted, because an Action can't remember anything between runs. That is why the checkboxes only work in the App. See [`packages/action`](packages/action) for providers, lenses, branding and the other inputs.
  271. </details>
  272. <details>
  273. <summary><b>On GitLab: the CI/CD component</b> · your pipeline · your key · one comment that updates</summary>
  274. <br>
  275. GitLab CI can post the same maps on a merge request. Add two masked variables: your model key, and a project access token with the `api` scope. The token is what posts the comment. Then add the component:
  276. ```yaml
  277. workflow:
  278. rules:
  279. - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  280. - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  281. include:
  282. - component: gitlab.com/coldteadotai/pr-lens/pr-lens@0.1.0
  283. ```
  284. The `workflow: rules` block must be in your own `.gitlab-ci.yml`. GitLab only runs merge request pipelines when that file asks for them, and rules inside an included component don't count. You need the access token because `CI_JOB_TOKEN` can't post comments. On GitLab.com, project access tokens need the Premium or Ultimate plan. On the Free plan, a personal access token with the `api` scope works too, but the comment shows your name instead of a bot's.
  285. The SVGs are uploaded to the project as attachments. That way everyone who reads the merge request can see them, even people who can't open files in the repository. On a private project, there is a downside. Anyone who has the attachment link can see the map, even if they are not a member. The link can't be guessed, but it is the only thing that protects the image. If a project turns on **Require authentication to view media files**, the images won't load. Readers can still open the maps from the canvas link in the comment. See [`packages/gitlab-component`](packages/gitlab-component) for more.
  286. </details>
  287. <details>
  288. <summary><b>On Bitbucket: the pipe</b> · your pipeline · your key · one comment that updates</summary>
  289. <br>
  290. On Bitbucket Pipelines, add the pipe under `pull-requests:`:
  291. ```yaml
  292. clone:
  293. depth: full # the diff needs history back to the merge base
  294. pipelines:
  295. pull-requests:
  296. "**":
  297. - step:
  298. name: PR Lens
  299. script:
  300. - pipe: docker://ghcr.io/coldteadotai/pr-lens-pipe:0.1.0
  301. variables:
  302. GEMINI_API_KEY: $GEMINI_API_KEY
  303. PR_LENS_TOKEN: $PR_LENS_TOKEN
  304. ```
  305. A pipe only sees the variables its step gives it, so the step passes in two secured variables by name. The first is your model key. The second is a repository access token with the `pullrequest:write` and `repository:write` scopes. The `repository:write` scope lets the pipe save the maps to the repository's Downloads. Every Bitbucket plan has repository access tokens. Tokens for a whole workspace need Premium.
  306. Bitbucket shows comments as plain Markdown. So the comment has no sections to open and close, and no light and dark pair. It shows the headline, the numbers, one map per lens, and then the zoomed-in views in order. Bitbucket never runs a pipeline for a pull request opened from a fork, so the pipe can't map those pull requests, no matter how you set it up. If your repository gets a lot of help from forks, use the hosted app. See [`packages/bitbucket-pipe`](packages/bitbucket-pipe) for more.
  307. </details>
  308. <details>
  309. <summary><b>From the CLI</b> · every step on your computer, one at a time</summary>
  310. <br>
  311. The CLI does everything the other options do, one step at a time, on your computer. Only `analyze` talks to a model. It reads the key from the environment, never from a flag:
  312. ```bash
  313. export GEMINI_API_KEY=… # the default provider; OPENAI_API_KEY with --provider openai
  314. # Diff in, graph document out — measured against the merge base, not the branch tip.
  315. npx @coldtea/pr-lens-cli analyze --base origin/main
  316. # The document as light and dark SVGs, plus the manifest a comment is built from.
  317. # Each drawing lands in its own directory under .pr-lens/, named after its title.
  318. npx @coldtea/pr-lens-cli render .pr-lens/graph.json
  319. # The pull request comment as markdown, on stdout. Posting is your business.
  320. npx @coldtea/pr-lens-cli comment --graph .pr-lens/<drawing>/drawn.graph.json --manifest .pr-lens/<drawing>/manifest.json \
  321. --asset-base-url https://raw.githubusercontent.com/owner/repo/pr-lens/42
  322. # Any PR Lens document, checked against the contract — every problem, not just the first.
  323. npx @coldtea/pr-lens-cli validate .pr-lens/graph.json .github/pr-lens.yml
  324. # After the merge: the pull-request document as a stored map of the system, worth committing.
  325. npx @coldtea/pr-lens-cli export .pr-lens/graph.json -o .github/pr-lens.map.json
  326. ```
  327. Everything goes in `.pr-lens/`. The first time the CLI writes there, it adds that folder to your `.gitignore`. Think of it as scratch space, because the CLI can rebuild those files from the diff at any time. The only file worth committing is the map that `export` writes. Use `--out` if you want the files somewhere else.
  328. `comment --target gitlab` or `--target bitbucket` writes a comment that GitLab or Bitbucket can show. `analyze` finds out which one you use from your git remote. To use Ollama, DeepSeek, OpenRouter, or anything else that speaks `/chat/completions`, pass `--provider openai-compatible --base-url <url>`. See [`packages/cli`](packages/cli) for every command, the fix file, and the error codes a script can check.
  329. </details>
  330. <details>
  331. <summary><b>In your terminal</b> · the map before the pull request exists</summary>
  332. <br>
  333. The maps don't need a pull request. Render them on your computer and look at the change before anyone else does:
  334. ```bash
  335. npx @coldtea/pr-lens-cli analyze --base origin/main
  336. npx @coldtea/pr-lens-cli render .pr-lens/graph.json
  337. open .pr-lens/*-dark-*.svg # macOS; the SVGs are self-contained, any browser reads them
  338. ```
  339. This also helps when you review an agent's work. While you read the diff, the agent that wrote it can map it. With the skill installed, say "render this change with PR Lens and open the SVGs". You get the map next to the diff, minutes before the pull request shows the same picture.
  340. </details>
  341. <br />
  342. ## Packages
  343. | Package | What it is |
  344. | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
  345. | [`packages/schema`](packages/schema) | `@coldtea/pr-lens-schema`: the format every other part uses |
  346. | [`packages/renderer`](packages/renderer) | `@coldtea/pr-lens-renderer`: turns a JSON graph into the moving light and dark SVGs on this page, the same way every time |
  347. | [`packages/cli`](packages/cli) | `@coldtea/pr-lens-cli`: reads a diff with your own model key, maps it, and writes the comment |
  348. | [`packages/action`](packages/action) | the GitHub Action: analyzes the change, publishes the maps, and posts one comment |
  349. | [`packages/gitlab-component`](packages/gitlab-component) | the GitLab CI/CD component: does the same on a merge request |
  350. | [`packages/bitbucket-pipe`](packages/bitbucket-pipe) | the Bitbucket pipe: does the same on a pull request |
  351. | [`packages/agent-skill`](packages/agent-skill) | `@coldtea/pr-lens-agent-skill`: teaches a coding agent to map the change it just made |
  352. <br />
  353. ## Working in this repo
  354. ```bash
  355. pnpm install
  356. pnpm verify # build, typecheck, test
  357. ```
  358. You need Node 20.11 or newer and pnpm 10.
  359. <br />
  360. ## Self-hosting the canvas
  361. Start with [docs/canvas-api.md](docs/canvas-api.md).
  362. <br />
  363. ## Community
  364. Ask questions or share your maps on [Discord](https://discord.gg/sGDwjs8yHK). We post new releases and features on X at [@ColdteaAI](https://x.com/ColdteaAI).
  365. <br />
  366. ## Contributing
  367. Open an issue first. Wait for one of us to approve it before you or your agents write any code. We close pull requests that have no approved issue. Once your issue is approved, link to it from your pull request.
  368. Commit under your own name only. Don't add a `Co-Authored-By` line for a model, a "Generated with" footer, or a session link. You can use an agent (we do too), but the commits are yours and you are fully responsible for them. Most tools add these lines unless you turn them off.
  369. <br />
  370. ## Why we built this
  371. [Reducing the cognitive load of reviewing PRs](https://www.coldtea.ai/blog/reducing-cognitive-load-ai-generated-prs)
  372. <br />
  373. ## License
  374. MIT © Coldtea

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.