How do I use PR Lens with Claude Code?

Run npx skills add coldteadotai/pr-lens in your repository, then ask Claude Code to diagram the change it just made with PR Lens. It reads the diff, writes a graph document, validates it against the contract, renders the SVGs, and attaches them to the pull request. There is no API key to configure, because the agent uses the model it is already running.

Does the PR Lens skill need an API key?

No. The skill has the agent author the graph document itself and validate it with npx @coldtea/pr-lens-cli validate. The only path in PR Lens that needs a provider key is the CLI's analyze command, and the skill does not use it unless you ask for it.

Which coding agents does the PR Lens skill work with?

Any tool that reads Agent Skills or a plain instructions file. SKILL.md is markdown with YAML frontmatter and assumes nothing beyond a shell and npx, so Claude Code, Cursor, OpenCode and others all work. Claude Code reads it from .claude/skills/pr-lens, and Cursor reads the same file as .cursor/rules/pr-lens.mdc.

The diagram named something wrong. How do I fix it?

Do not edit the generated document, because it is rebuilt on every run. Write the fix into .github/pr-lens.yml as a rename, an exclusion, a lane pin or a grouping. The skill teaches the agent to do this, and pr-lens render reports any correction that matched nothing, so a config that drifts becomes visible instead of failing quietly.

Reference

PR Lens as an agent skill: draw a change from inside Claude Code, Cursor or OpenCode

Install the PR Lens skill with npx skills add coldteadotai/pr-lens and your coding agent draws the change it just made, using the model it already runs. No key to set up.

Ohans Emmanuel21 August 20267 min read

The kind of picture an agent hands back after one change.

Install the skill with npx skills add coldteadotai/pr-lens, then say to your agent: diagram the change you just made with PR Lens and attach it to the pull request. It reads the diff, writes a graph document, validates it, renders the SVGs and puts them where a reviewer will see them. There is no API key in this path. The skill works in Claude Code, Cursor, OpenCode and anything else that reads Agent Skills or a plain instructions file, because SKILL.md is markdown with YAML frontmatter and assumes nothing beyond a shell and npx.

The reason this route exists is arithmetic. Your agent already read the diff. Paying a second model to describe it is paying twice.

Installing it

The one-liner pulls the skill from the repository into your project:

npx skills add coldteadotai/pr-lens

It is also on npm, which is what you want if you would rather pin a version and check the file into the repository:

npm install --save-dev @coldtea/pr-lens-agent-skill

For Claude Code, copy it where skills live, per project or per user:

mkdir -p .claude/skills/pr-lens
cp -R node_modules/@coldtea/pr-lens-agent-skill/{SKILL.md,references} .claude/skills/pr-lens/

For Cursor, the same file works as a rule:

mkdir -p .cursor/rules
cp node_modules/@coldtea/pr-lens-agent-skill/SKILL.md .cursor/rules/pr-lens.mdc

For anything else, point your agent's instructions file at SKILL.md.

Four files come with it. SKILL.md is when to reach for PR Lens and the loop to run. references/graph-document.md is the document field by field, with the limits and the places documents actually go wrong. references/config.md is the correction format in full. There is also references/example.graph.json, one complete document that validates: three lanes, all four delta states, a hero edge, a seven-step flow, a nested drill-down tree and a six-step walkthrough. The skill tells the agent to read the example before the reference, because it is quicker.

What the skill teaches

Five steps, and the third is the one that makes the whole thing work.

Read the diff with git diff --find-renames <base>...<head>, where the base is the merge base and not the tip of the base branch. A diff against the tip blames this change for everything that landed on main since it forked.

Write the document to .pr-lens/graph.json.

Validate it:

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

Fix every failure and run it again. The skill is explicit that the agent must not render an invalid document, and must not work around a failure by deleting the element the error names. Every failure is a path into the document, so the loop closes without a human in it. Four codes account for nearly everything: BROKEN_REFERENCE when an edge or a walkthrough step names an id that was never declared, INVALID_DOCUMENT for an invented field, DUPLICATE_ID, and UNSUPPORTED_SCHEMA_VERSION.

Render it:

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

Then attach it, when there is a pull request to attach to.

Getting the picture into the pull request

GitHub CLI uploads the file with the pull request. The agent writes the body with a Markdown image pointing at the local path, then passes the same path to --attach, and gh rewrites the reference to the uploaded asset while keeping the alt text:

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

Three rules go with it. 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 what a reader without images gets, so it says what the diagram shows in one line. And --attach arrived in GitHub CLI 2.99, so the skill has the agent check gh --version before writing a body around it.

The diagram goes in the description rather than a trailing comment. A reviewer should meet the picture before the diff, and a comment sits below it.

If you asked for a diagram and nothing else, the skill hands back a link instead:

npx @coldtea/pr-lens-cli@latest canvas push

That prints a view link at prlens.dev/c/<id>: the diagrams full screen, every view on one page, no login. It also prints an edit link carrying a write token in its fragment, which the skill tells the agent to keep out of the reply unless you ask. Pushing the same file again updates the same canvas, so "rename that node" is edit, validate, render, push, and the link you already shared still works.

What makes a document worth reading

The skill spends more words on judgement than on syntax, because a valid document can still be a useless picture.

Include what did not change. A diagram of only the changed nodes says nothing about blast radius, so unchanged neighbours belong in the document marked delta: "unchanged". Lanes are the reader's mental model, a runtime or a tier or a boundary, and not the folder tree. One hero edge, two at the outside: the connection the change is really about. A flow only when there is a sequence worth animating, because one good flow beats three thin ones.

And there is no findings lens. PR Lens is the comprehension layer. There is no field for a bug, a risk or a security note, and a document that invents one is rejected rather than trimmed. If your agent wants to tell you the code is wrong, it can say so in words; it does not get to say it in the diagram.

Walkthroughs, and the writing standard

A walkthrough is a short guided tour: two to twelve steps, three to seven in practice, each showing one diagram, pointing at one part of it, and saying a few words. The canvas plays it.

Each step is one change, in the order a reviewer needs it. The heading names the thing and what happened to it, in 48 characters or fewer, built from change words: added, removed, replaced, now, moved, split. The test in the skill is sharp. If a heading could have been true before the pull request, it is not a change heading.

The body under it is one line, up to 140 characters, on what the change means for behaviour. The skill asks for words a smart twelve-year-old would read without stopping: short common words, active voice, things named the way the diagram names them, numbers as digits. It bans a specific vocabulary by name. Leverages, orchestrates, asynchronous pipeline and fan-out never belong in a step.

Here is the difference it is asking for, taken from the table in the skill. Write "Route now queues the job instead of sending / The API call finishes at once. A worker sends the mail later." Do not write "Broadcast fan-out moves behind the queue / The API route now enqueues broadcast jobs for asynchronous batch processing instead of sending emails inline."

Every id a step names is checked against the document, so a step cannot point at a node that is not drawn.

Fixing a map instead of editing output

When the diagram names something wrong, or puts a package in the wrong lane, or draws a folder that should not be there, the fix is never to edit the generated document. That file is regenerated on the next run.

schemaVersion: 0.1.1
map:
  rename:
    - match: functions/src/broadcast/sendBroadcastBulk.ts
      to: Broadcast sender
  exclude:
    - "**/*.test.ts"
  lane:
    - match: packages/broadcast-lib/**
      lane: functions

That file is an overlay applied over fresh inference every time, so the correction keeps holding as the code moves. A match beginning with id: addresses one node exactly; anything else is a path glob against a node's file paths, and the glob is usually the right choice because it survives the model renaming the node. pr-lens render reports any correction that matched nothing, which is how a config that drifted because a file moved becomes visible rather than silently doing nothing. The whole format is in configuring PR Lens.

When to use the skill, and when not to

The skill is the author's tool. It draws the change while the agent still has the context that made it, minutes before anyone opens the pull request, and it costs you nothing beyond tokens you were already spending.

It does not redraw on every push, because nothing is watching the repository. For that you want the hosted App, which keeps a baseline of the repository and rewrites one sticky comment as the branch moves: see installing the PR Lens GitHub App. Many teams run both. The agent attaches a diagram when it opens the pull request, and the App keeps that pull request drawn as it changes.

If you would rather drive the same pipeline by hand, every command the skill runs is documented in the PR Lens CLI, and the shape of the document the agent writes is in the PR Lens graph document explained. For the wider picture, start at what is PR Lens.

Questions people ask

How do I use PR Lens with Claude Code?: Run npx skills add coldteadotai/pr-lens in your repository, then ask Claude Code to diagram the change it just made with PR Lens. It reads the diff, writes a graph document, validates it against the contract, renders the SVGs, and attaches them to the pull request. There is no API key to configure, because the agent uses the model it is already running.
Does the PR Lens skill need an API key?: No. The skill has the agent author the graph document itself and validate it with npx @coldtea/pr-lens-cli validate. The only path in PR Lens that needs a provider key is the CLI's analyze command, and the skill does not use it unless you ask for it.
Which coding agents does the PR Lens skill work with?: Any tool that reads Agent Skills or a plain instructions file. SKILL.md is markdown with YAML frontmatter and assumes nothing beyond a shell and npx, so Claude Code, Cursor, OpenCode and others all work. Claude Code reads it from .claude/skills/pr-lens, and Cursor reads the same file as .cursor/rules/pr-lens.mdc.
The diagram named something wrong. How do I fix it?: Do not edit the generated document, because it is rebuilt on every run. Write the fix into .github/pr-lens.yml as a rename, an exclusion, a lane pin or a grouping. The skill teaches the agent to do this, and pr-lens render reports any correction that matched nothing, so a config that drifts becomes visible instead of failing quietly.

Sources

Keep reading

Turn it on

Install the App and every pull request in the repositories you pick gets drawn. Or hand the prompt to the agent you already have open.

Add to GitHub