coldteadotai/pr-lens

PR Lens – visual review of pull‑requests

What it does

• When a pull request (PR) is opened, PR Lens posts a comment that contains an animated architecture‑style diagram of the change. The diagram shows which files, services or components are added, modified or removed (green / amber / red) and the data‑flow between them.
• The comment is interactive: it expands into <details> sections that let you focus on the whole “blast radius”, just the new code path, or the retired parts.
• Each diagram can be opened in a full‑size canvas where you can pan, zoom and switch between light and dark themes. A walkthrough mode steps through the change one operation at a time, highlighting the affected nodes and routes.

How you get it

1. GitHub App – Install the coldtea‑pr‑lens app on any repository. The app automatically analyses each PR, renders the SVGs and updates the comment on every push.
2. GitHub Action – Add a workflow (.github/workflows/pr‑lens.yml) that runs the same analysis in your CI, using your own LLM API key (Gemini by default, but OpenAI or any /chat/completions endpoint works).
3. CLI – Run the @coldtea/pr‑lens‑cli locally to analyze a diff, render SVGs, generate the markdown comment, validate the generated graph, or export a persistent map of the system.
4. Agent skill – Install the skill (npx skills add coldteadotai/pr‑lens) so a coding assistant (Claude, Gemini, Copilot, etc.) can write the graph document and post the comment automatically.

Key components

Package	Role
@coldtea/pr‑lens‑schema	JSON schema that defines the graph contract shared by all parts
@coldtea/pr‑lens‑renderer	Turns the JSON graph into deterministic, animated SVGs (light/dark pairs)
@coldtea/pr‑lens‑cli	CLI that talks to an LLM to turn a git diff into a graph, renders SVGs, builds the comment, validates, and can export a map
pr‑lens GitHub Action	CI‑friendly wrapper that runs the CLI and posts a static comment
@coldtea/pr‑lens‑agent‑skill	Small “skill” that teaches a coding agent to generate the graph and post it

Configuration

• Add a .github/pr‑lens.yml file to rename, exclude or group files, pin lanes, etc. The file is an overlay that stays valid as the code evolves.
• The CLI automatically creates a .pr‑lens/ folder (git‑ignored) for temporary files; the only artifact you might commit is the exported map (.github/pr‑lens.map.json).

Why it matters Reviewing large PRs can be mentally taxing. PR Lens turns the textual diff into a visual map that shows what parts of the system are touched and how data moves through them, letting reviewers grasp the impact before reading line‑by‑line code.

Where to see it

• Live examples are linked in the “Hall of Fame” (e.g., React Hooks, Node fetch, Kubernetes Ingress, vLLM). Each shows a real‑world PR rendered by PR Lens.
• The web UI (prlens.dev) hosts the interactive canvases.

Getting started

# Install the GitHub App (or add the Action)
# Or run locally:
export GEMINI_API_KEY=YOUR_KEY   # or OPENAI_API_KEY
npx @coldtea/pr-lens-cli analyze --base origin/main
npx @coldtea/pr-lens-cli render .pr-lens/graph.json
open .pr-lens/*-dark-*.svg

License – MIT.