PR Lens
Turn code changes into animated architecture and data-flow diagrams so reviewers can see the change before reading the code.
- Source repo
- coldteadotai/pr-lens
- Stars
- ★ 1.9k
- Last updated
- 5d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 61/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex
- Cost
- Free tier plus a paid hosted plan
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A reviewer wants to locate affected components and call paths in a large PR before reading its files one by one.
- Not a fit if
- Teams that require analyzed diffs to stay within their own environment
- Teams that need Bitbucket pipelines to run on fork pull requests
- Source review
- 61/100 · Some gaps 1 safety controls not found
What does this agent do, and when should you use it?
PR Lens can run as a GitHub App, GitHub Action, CLI, or coding agent skill to draw architecture and data-flow views of pull requests. Its shared graph format is JSON defined by `@coldtea/pr-lens-schema`, which `@coldtea/pr-lens-renderer` renders as self-contained light and dark SVGs. The GitHub App posts diagrams in a PR comment and updates that comment on later pushes; the CLI and Action can analyze diffs with a model key you provide. GitLab CI/CD component and Bitbucket pipe integrations bring diagram generation into those review workflows too. It suits teams that want a visual map of changes across components; teams running their own analysis need to account for model credentials and pipeline setup.
PR Lens reads a code diff against its merge base and, in the analysis path, calls the selected model to produce graph JSON. @coldtea/pr-lens-cli analyze runs analysis, render writes light and dark SVGs for each drawing, validate checks a graph and repository configuration, comment outputs Markdown for a target forge, and export can write a system map. Diagrams use lanes, cards, and connecting paths to show affected components and calls; architecture views mark additions in green, changes in amber, and removals in red. Data-flow views step through a path and let readers inspect the request or response shape carried by an arrow. The GitHub App, GitHub Action, GitLab component, and Bitbucket pipe connect drawings to their review workflows; the coding agent skill lets a compatible local coding agent draw a code change.
- A reviewer wants to locate affected components and call paths in a large PR before reading its files one by one.
- A monorepo maintainer needs to see which lanes, components, and data-flow steps a change crosses.
- A developer using a coding agent wants SVGs of its changes before opening a pull request.
- A GitHub team wants the App to post diagrams in a PR comment and update them on every push.
- A GitLab or Bitbucket team wants review diagrams generated through a CI/CD component or pipe.
How do you install or deploy this agent?
Install the local CLI or coding agent skill with the commands below. The repository specifies Node 20.11 or newer and pnpm 10; GitHub App users can install it from the App page. For Action, GitLab component, or Bitbucket pipe deployments, configure the model key and the comment permissions or token required by that integration.
npx skills add coldteadotai/pr-lenspnpm installHow do you use this agent?
For first-run CLI analysis, set an API key for the model provider. Gemini is the default; OpenAI and services compatible with /chat/completions are also supported. These commands analyze changes from the merge base with origin/main and render SVGs:
export GEMINI_API_KEY=…
npx @coldtea/pr-lens-cli analyze --base origin/main
npx @coldtea/pr-lens-cli render .pr-lens/graph.jsonThe CLI can also run validate, comment, and export after analysis. The GitHub Action example runs on pull_request; save the model key as a repository secret and grant permission to publish SVGs and write PR comments:
name: PR Lens
on:
pull_request:
permissions:
contents: write
pull-requests: write
jobs:
lens:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: coldteadotai/pr-lens/packages/action@v0
with:
api-key: ${{ secrets.GEMINI_API_KEY }}What are this agent's strengths and limitations?
- Its custom renderer produces animated SVGs and uses distinct colors for added, changed, and removed code.
- PR comments support foldable diagram sections, with a zoomable, pannable canvas and step-by-step walkthroughs also available.
- The project documents GitHub App, CLI, GitHub Action, GitLab component, Bitbucket pipe, and coding agent skill entry points.
- The Action and CLI can use Gemini, OpenAI, or a provider compatible with
/chat/completions.
- CLI and user-managed CI analysis require a model API key; the diff is sent to the provider you select.
- The repository specifies Node 20.11 or newer and pnpm 10; CLI use also requires a local Git repository and shell.
- Bitbucket does not run pipelines for pull requests from forks, so its documented pipe cannot draw those PRs.
- Bitbucket comments are plain Markdown, without foldable sections or paired light and dark diagrams.
How does this agent compare with similar options?
The README explicitly contrasts PR Lens with Mermaid: PR Lens uses a custom renderer for animated diagrams and represents code additions, removals, and changes. It does not provide a feature or price comparison with other alternatives.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| PR Lens This agent | 61 · Some gaps | Agent plugin / skillFreemium | ★ 1.9k | 5d ago | TypeScript | Codex |
| Vet Code Change Verifier | 65 · Some gaps | CLIFree + model costs | ★ 521 | 25d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| Coder Eval | 86 · Good | CLIFree + model costs | ★ 151 | 2d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| no_human | 67 · Some gaps | CLIFree + model costs | ★ 324 | today | Python | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The README says the Action passes the key to the CLI through the environment, sends the diff to the selected model, and notes that someone with a GitLab private-project attachment link can access it; this supports a score of 2 for data-flow transparency. The Action example grants contents: write and pull-requests: write, and the GitLab and Bitbucket setups require write-capable tokens, but the materials do not narrow these permissions or explain revocation, so least privilege scores 1. There is no general per-run confirmation or rollback guidance for posting or editing comments, so user confirmation scores 1, external effects 1, and rollback 0. Key handling is described, but full sensitive-data retention or hosted-service handling details are absent; there is also no dependency audit or mitigation evidence, so sensitive-data handling and dependency security each score 1. SECURITY.md provides a contact route, but the supplied materials do not verify publisher identity or external claim sources, so source attribution scores 1.
The README describes the App, Action, CLI, and configuration paths; the supplied Action test source also checks consistency among inputs, scripts, CLI versions, and comment ownership, supporting a self-consistency score of 2. Test source provides evidence about intended behavior, but the materials do not establish dependency availability or locking sufficiently, so that criterion scores 1. Action tests require publish-script retries and check that failure to look up the PR head produces a clear error; these are source-level failure-handling indicators, so failure messages score 2.
The README covers reviewers, coding agents, CI users, multiple forges, and workflows before and after a PR, so audience and scenarios score 3. Differences among the CLI, Action, and hosted service are described, including unavailable Action comment checkboxes, Bitbucket fork PR behavior, and GitLab private-attachment access limits, so capability boundaries score 2. Trigger examples are reasonably specific, including pull_request and GitLab merge-request rules, but the App's full event scope is not in the supplied materials, so trigger precision scores 2. Node requirements, platform setup, and provider choices are documented, so environment fit scores 3.
The README is organized by features, configuration, and operating modes and links to package documentation, but the supplied text ends at the package table, so information architecture scores 2. Setup steps, configuration examples, required keys, and permissions are detailed, so install notes score 3. Package names and commands are broadly consistent, but multiple packages and version labels appear without a complete release policy, so naming stability scores 2. The README gives practical examples and several common limitations, but no complete FAQ is visible, so examples and FAQ score 2. It explicitly documents fork, attachment-access, and platform limitations, earning 3 for known limitations. The MIT LICENSE file is complete, earning 3 for license. The root package is version 0.0.0 and examples use v0 and 0.1.0, but no changelog is supplied, so versioning and changelog score 1. SECURITY.md gives a vulnerability-report email and response commitment, but no maintainer roster or release-ownership process, so maintenance responsibility scores 2.
The README shows diagrams in comments, layered views, an interactive canvas, and guided walkthroughs; the CLI also offers validation and export flows, supporting an output-usability score of 3. Visualizing PR changes may reduce comprehension effort and examples cover large changes, but the evidence is mainly project-authored claims and showcase images, so marginal value scores 2. Free open-source use and multiple operating modes help users manage cost, while model calls, key management, and CI write permissions add practical cost or overhead, so cost-benefit scores 2.
The README maps feature descriptions to package docs, configuration references, and forge-specific examples, making some claims traceable; the linked files themselves are not included, so claim traceability scores 2. README claims are partly corroborated by Action, comment-script, and skill-mirror test source; cross-source corroboration scores 2. These tests are reviewed only as source evidence, with no claim that they were run. Descriptions, showcase images, and product-effect claims do not consistently distinguish implemented behavior from promotional inference, so fact-inference separation scores 1.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Before using the Action, GitLab CI, or Bitbucket pipe, review the required write permissions and token scopes; GitLab private-project attachment links may expose diagrams to link holders outside the project.
- The selected model provider receives the code diff; check its data-handling terms against your repository requirements.
FAQ
Do I need a paid model API key to use PR Lens?
/chat/completions.What does PR Lens read, and where does analysis go?
analyze calls a model; with the CLI or your own Action, the diff is sent to the model provider you select.Can I draw a change before opening its pull request?
analyze --base origin/main and then render with the CLI. With the skill installed, you can also ask a coding agent to draw its changes.Can the Bitbucket pipe handle pull requests from forks?
Which permissions does the GitHub Action need?
contents: write to publish SVGs and pull-requests: write to post comments. It also expects the model key to be stored as a repository secret.