---

name: pr-lens description: "WHAT: Draws a code change or part of a codebase as an animated architecture or data-flow diagram, on its own or in a pull request. WHEN: asked to diagram, visualise or explain a change or a system, or when a pull request should carry a diagram. KEYWORDS: PR Lens, diagram, architecture, data flow, visualise, visualize, pull request"

PR Lens

PR Lens draws code as visually rich animated diagrams. It can represent diffs, architecture, data flows, and more.

The diff or code is represented as one JSON document (lanes, nodes, edges, ordered flows) and it renders the JSON as an animated SVG

Operating manual

Decide where the diagram lands before you write it: a canvas, or an SVG and a pull request comment. Only a canvas draws payload, the sample request and response on a flow step. A late decision costs another pass through steps 2 and 3.

1. Read the diff. When asked to represent a code change: git diff --find-renames <base>...<head>. The base is the merge base, not the tip of the base branch.

   If not expressing a code diff, read the code to be visually represented

2. Write the document to .pr-lens/graph.json, following references/graph-document.md. references/example.graph.json is valid reference with three lanes, all four delta states, a hero edge, a seven-step flow, a nested drill-down tree and a six-step walkthrough. Read it before you write your first one. It is quicker than reading the reference. If it is going to a canvas, give every flow step (messages) that moves data a payload as you write it. "Sample traffic on a flow step" below says what goes in one. Only a flow step carries one. Flows need the data-flow lens, so an architecture view draws none.

3. Validate, and fix

   npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.json
   

   Fix every failure and run it again. Do not render an invalid document; do not "work around" a failure by deleting the element it names.

4. Render.

   npx @coldtea/pr-lens-cli@latest render .pr-lens/graph.json --theme light
   

   Render light by default unless the user requests another theme. The SVGs, the manifest and drawn.graph.json land in a directory of their own under .pr-lens/, named after the document's title. The render prints that path, so read it from there. The CLI adds .pr-lens/ to the repository's .gitignore. Do not commit any of it. These files are rebuilt from the diff whenever anyone wants them again. Each SVG is named after its view, the theme and a content hash; manifest.json lists them by lens and view, so read the names from there or from the directory.

   If the user asked for a diagram, an explanation or a picture of the architecture and nothing more, put it on a canvas and hand back the link:

   npx @coldtea/pr-lens-cli@latest canvas push .pr-lens/<drawing>/drawn.graph.json
   

   Pass the path the render printed. A bare canvas push finds the drawing when the checkout holds only one; with more than one it lists them and asks which, so always pass the path.

   It prints three links. Give the user the view link, https://prlens.dev/c/{id}: that is the diagram, full screen, every view on one page, and it opens without a login. The edit link, the one ending in #w=…, lets its holder push over the canvas, so leave it out of the reply unless they ask, and never paste it anywhere public. The embed link serves the top view as an SVG for a README.

   Pushing the same document again updates the same canvas, so a follow-up such as "rename that node" or "add the queue" is: edit the document, validate, render, push. While the title stays the same, it renders to the same directory and pushes to the same canvas, so the link does not change. If the push fails, say so and tell them where the SVGs are and which one is the top view.

   A different diagram only needs a different title. It renders into its own directory and pushes to its own canvas, and the first one stays as it was. canvas list shows them all.

5. Attach, when there is a pull request to attach to. That means the user asked you to open a PR, asked for a diagram on one that exists, or you are opening a PR as part of changes made. Otherwise skip this step.

How the diagram gets there depends on the forge. Run git remote get-url origin to see the host before you write a body around a flag that forge may not have.

GitHub. GitHub CLI uploads the diagram with the pull request. Write the body with a Markdown image pointing at the local file, then pass the same path to --attach. gh rewrites the reference to the uploaded asset and keeps the alt text you wrote:

Moves bulk sending off the per-recipient trigger and onto a batch endpoint.

![Architecture after this change: the queue route, the new bulk sender and the retired per-recipient path](.pr-lens/overview-light-4f9bd6c1.svg)

gh pr create --title "Batch broadcast sends" --body-file .pr-lens/body.md \
  --attach .pr-lens/overview-light-4f9bd6c1.svg

On a pull request that already exists, gh pr edit <number> with the same two flags puts the diagram in the description, and gh pr comment <number> puts it in a comment. Repeat --attach for each diagram the body references.

gh has three rules:

• The reference has to be a Markdown image, ![alt](path). An HTML <img> or <picture> is left as written, and the file is appended at the bottom of the body instead.
• The alt text is the caption a reader without images gets. Say what the diagram shows, in one line.
• --attach arrived in GitHub CLI 2.99. Check with gh --version before you write a body around it.

Attach the views a reviewer needs and leave the rest in .pr-lens/: the top architecture view first, then a data flow if the change has a sequence worth following. A body with four diagrams reads worse than one with two, except the four are really needed to understand the change e.g., in the case of a complex feature or refactor.

GitLab. Nothing uploads the file with the description for you, so upload each SVG to the project first. The response includes the Markdown to paste into the description:

curl -sf --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
  --form "file=@.pr-lens/overview-light-4f9bd6c1.svg" \
  "https://gitlab.com/api/v4/projects/<url-encoded-path>/uploads"
# → {"markdown":"![overview-light-4f9bd6c1](/uploads/…/overview-light-4f9bd6c1.svg)", …}

glab mr create --title "Batch broadcast sends" --description "$(cat .pr-lens/body.md)"

An uploaded image loads for every reader of the merge request. A raw file URL on a private project does not. The catch is that the attachment URL is the permission: it is unguessable, but anyone who has it can see the diagram, member or not. Tell the user this if the project is private. GitLab strips <picture>, so render with --theme neutral and reference that single SVG. The neutral render has its own background and reads in both light and dark mode. Either half of the light/dark pair looks wrong in one of them.

Bitbucket. Comments and descriptions are plain Markdown with no HTML, so there are no collapsible sections or theme pairs. Render with --theme neutral here too. Publish the SVGs somewhere durable, such as the repository's Downloads or a canvas, and reference them as ordinary Markdown images.

On any forge where --attach is not an option, publish the SVGs somewhere durable and let the CLI compose the comment instead:

npx @coldtea/pr-lens-cli@latest comment \
  --graph .pr-lens/<drawing>/drawn.graph.json \
  --manifest .pr-lens/<drawing>/manifest.json \
  --asset-base-url https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<dir>

--graph takes the drawing's own drawn.graph.json, not the document you wrote, because corrections change what the diagrams show and the CLI refuses a document its manifest does not describe. --asset-base-url is where you published the SVGs; leave it out and the markdown points at local paths no reader can fetch. The markdown goes to stdout, with each diagram as a <picture> pair; posting it is your business.

Add --target gitlab or --target bitbucket when the comment is not for GitHub, so the composer writes markup that forge can render. GitHub gets <picture> theme pairs and collapsible drill-downs. GitLab gets the same HTML with the single neutral render. Bitbucket gets plain Markdown with the views flattened. With the wrong target, the comment shows its tags as raw text.

If you would rather not author the document yourself, npx @coldtea/pr-lens-cli@latest analyze --base <ref> does steps 1 and 2 by asking a provider — Gemini, OpenAI, or any endpoint speaking /chat/completions — with a key of your own. That is the only path here that needs one.

Answering beside an open canvas

Once a canvas is pushed, you can answer questions about it on the canvas itself. The reader keeps the page open, asks you in the terminal, and your answer plays there: the camera moves step by step, what you name lights up, and each name is a link.

Run this once, when the user wants to talk about a canvas they have open or are about to open. Name the drawing you pushed, the same path as the push:

npx @coldtea/pr-lens-cli@latest canvas open .pr-lens/<drawing>/drawn.graph.json

It opens one browser tab that follows you. Only that tab moves. Anyone else reading the same link sees the canvas as it was. Every command below talks to that tab, and takes the same path as --drawing. Always pass it: a checkout can hold several canvases, and the path says which one you mean.

When the user gives you a link to a canvas you did not push, like https://prlens.dev/c/<id>, open it with the link. This works from any folder, as long as the canvas is not private:

npx @coldtea/pr-lens-cli@latest canvas open --canvas https://prlens.dev/c/<id>

The CLI saves a copy of the drawing to .pr-lens/canvases/<id>.graph.json. Take the ids for your answer from that file. In the commands below, use --canvas <id> in place of --drawing. A private canvas opens only for its owner, after they run npx @coldtea/pr-lens-cli@latest auth login.

When the user says "this", "here" or "what I selected", look first. They clicked a component, dragged a box or picked a part of a drawing in the tab, and you cannot see it:

npx @coldtea/pr-lens-cli@latest canvas look --drawing .pr-lens/<drawing>/drawn.graph.json

It prints JSON: the diagram they are on (diagram.stage, ready to paste into a step), what is on screen (inFrame), what they selected (scope), the answer they have open, and the drawing hung under the canvas (fork), if there is one. Answer about scope when it is set. following: false means they left agent mode: tell them the answer is waiting rather than saying you moved their canvas.

Answer with a JSON file, or - to pipe it in:

npx @coldtea/pr-lens-cli@latest canvas answer .pr-lens/answer.json --drawing .pr-lens/<drawing>/drawn.graph.json

{
  "question": "What does push check first?",
  "steps": [
    {
      "heading": "Push checks the token first",
      "stage": { "kind": "view", "view": "overview" },
      "focus": { "kind": "selection", "nodes": ["canvas-api"] },
      "paragraphs": [
        {
          "parts": [
            { "text": "The " },
            { "text": "canvas API", "ref": { "kind": "component", "id": "canvas-api" } },
            { "text": " refuses a push without the write token, before it draws anything." }
          ]
        }
      ]
    }
  ]
}

• One to four steps. Two is usual. Each step stops on one diagram, in the order a reader should follow.
• heading is a sentence of at most six words: who or what, a verb, what happens. The first step's heading is the answer. To a