pr-lens
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
coldteadotai · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add coldteadotai/pr-lens --skill pr-lensAbout this skill
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
-
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
-
Write the document to
.pr-lens/graph.json, followingreferences/graph-document.md.references/example.graph.jsonis 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. -
Validate, and fix
npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.jsonFix every failure and run it again. Do not render an invalid document; do not "work around" a failure by deleting the element it names.
-
Render.
npx @coldtea/pr-lens-cli@latest render .pr-lens/graph.json --theme lightRender light by default unless the user requests dark theme. The SVGs, the manifest and
drawn.graph.jsonland in.pr-lens/, which the CLI adds 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.jsonlists 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 pushThis pushes
.pr-lens/drawn.graph.jsonand 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 file 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. The link stays the same. If the push fails, say so and tell them where the SVGs are and which one is the top view.
-
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.
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.ghrewrites 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. gh pr create --title "Batch broadcast sends" --body-file .pr-lens/body.md \ --attach .pr-lens/overview-light-4f9bd6c1.svgOn a pull request that already exists,
gh pr edit <number>with the same two flags puts the diagram in the description, andgh pr comment <number>puts it in a comment. Repeat--attachfor each diagram the body references.gh has three rules:
- The reference has to be a Markdown image,
. 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.
--attacharrived in GitHub CLI 2.99. Check withgh --versionbefore 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.When
--attachis 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/drawn.graph.json \ --manifest .pr-lens/manifest.json \ --asset-base-url https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<dir>--graphtakesdrawn.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-urlis 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. - The reference has to be a Markdown image,
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.
The pull request body, when there is one
A reviewer should understand the change before reading the diff, so the diagram goes where they look
Read the complete source ↗