/pr-guide
GitHub Set it up

pr-guide turns a big pull request into chapters you can actually review.

Add to GitHub Actions Install in Claude Code →

Free and open source. Bring your own Claude API key.

From a wall of files to a reviewed PR. Try the real guide yourself, the one the Action wrote for this demo PR.

Reviewing starts with a wall of files in alphabetical order. pr-guide reads the diff and gives you a story instead: what changed, in what order to read it, and where to look hard.

Chapters by intent, not by file Related hunks are grouped by what they do and ordered so each chapter builds on the last. Tests stay next to the code they cover.

The guide's chapter list: implement the token bucket, apply limits to the link routes, count down in the shorten form.

It tells you what to check Each chapter says why the change exists, where to start reading, and the specific things worth verifying, riskiest first. On this PR, it caught an API-key bypass in the new rate limiter.

Chapter 2's explanation, ending in a list of checks that starts with a likely bypass: clientKey accepts any x-api-key value.

See the flow before the code A before/after diagram traces a request through the change, with each step tagged by the chapter that introduces it.

Flow diagram: ShortenForm calls shorten(), which posts to /links, passes rateLimit() and TokenBucket.take(), and a 429 becomes a countdown.
Every hunk, exactly onceA deterministic check places every changed hunk in one chapter, so nothing slips past.
About a minuteThe demo PR's guide took 62 seconds on GitHub, start to comment.
One comment, kept currentEach push updates the same PR comment instead of adding another.

Set up

Two ways to use it. Add it to a repo so every pull request gets a guide, or run it yourself from Claude Code on any PR.

  1. Tell us your repo

    Optional. The commands and links below fill in with it.

    Repository and default branch, for example acme/api and main.

  2. Add your Claude API key as a secret

    Create a key at console.anthropic.com (it starts with sk-ant-api). Usage is billed to that account, separately from any Claude subscription.

    gh secret set ANTHROPIC_API_KEY --repo owner/repo
    Or in the browser: Open the secrets page

  3. Add the workflow

    One click opens GitHub with the file already written. Commit it to your default branch.

    Create the workflow on GitHub
    name: PR guide

on:
  pull_request:
    types: [opened, ready_for_review, synchronize]

# One guide per PR at a time; a new push cancels the run for the old commit.
concurrency:
  group: pr-guide-${{ github.event.pull_request.number }}
  cancel-in-progress: true

permissions:
  contents: read
  pull-requests: write

jobs:
  guide:
    if: ${{ !github.event.pull_request.draft }}
    runs-on: ubuntu-latest
    steps:
      - uses: giovannivitale4722/pr-guide@v1
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

    Saved as .github/workflows/pr-guide.yml.

  4. Open a pull request

    The guide arrives as a comment in about a minute, with a link to the interactive page. Draft PRs wait until they're marked ready.

    See an example PR
Options
InputDefaultWhat it does
modelclaude-opus-5-5Model that groups the diff into chapters.
effortmediumGrouping effort, low to max. The main speed lever.
explain-modelsame as modelWrites chapter explanations on larger PRs. claude-sonnet-5-5 is faster.
explain-effortlowEffort for chapter explanations.
speedstandardfast uses Opus fast mode: faster output at 2x price.
commenttruefalse skips the PR comment and only uploads the page.

How it works

Grounded in research on splitting tangled changes and ordering code for review. Read the write-up.

  1. FetchSplit the diff into hunks and index which names each hunk defines and uses.
  2. GroupClaude puts hunks into chapters by intent, definitions before uses, riskier first.
  3. CheckCode, not a model, verifies coverage, chapter size and test placement.
  4. ExplainLarger PRs get each chapter written in parallel, so it stays fast.
  5. RenderThe PR comment plus the interactive page, with every hunk placed once.

Questions

Is this a code review?

No. It explains what the PR does and points at what deserves a careful look. Code the guide doesn't mention isn't verified, so a person still reviews.

What does it cost?

pr-guide is free. The Action calls the Claude API with your key: one call for small PRs, and one grouping call plus one per chapter for larger ones. Each run saves its token counts in run.json. The Claude Code skill runs in your existing session.

Where does my code go?

The diff is sent to the Claude API with your key. The guide page is stored as a workflow artifact in your repo, so only people who can read the repo can open it, and it expires with your artifacts (90 days by default).

Does it run on pull requests from forks?

Not by default. GitHub doesn't give fork PRs access to repository secrets, so the Action has no API key to use. You can still run the Claude Code skill on any PR you can read.

What about huge PRs?

Large diffs are clipped per hunk to fit, and the model is told which hunks were clipped. Lockfiles and snapshots go into a separate "Generated files" chapter.

Read your next PR in chapters.

Add to GitHub Actions Install in Claude Code