Understand a pull request before you review it.

MergeBrief turns a pull request into an AI brief: changes grouped, explained in plain language, and marked where to look closer.

Bring your own key or sub.

Free to self-host and modify. Source-available, Apache-2.0 after two years.

See the story and the intent.

A pull request tells a story: what the author set out to do, how the change gets there, and what it puts at risk.

Preview idan91/mergebrief #625
A demo example, based on a real pull request.Open the full demo

Summary

Start with the summary.

An overview and a changelog in plain language, before a single line of diff.

Change-groups

Changes, grouped by intent.

Chunks that do one piece of work sit together. Each group carries its category and its own summary.

Chunks

Then the diff, chunk by chunk.

Each chunk sits in its group by what it changes. Read it unified or split, on a phone as well.

Risk Surface

Know where to look closer.

Risk Surface attributes state facts about a chunk, such as hot path or dense logic. They are never verdicts.

Intent check

Hold the PR to its word.

The title, description and linked ticket are checked against the diff: what was promised but is missing, what changed but was never mentioned.

Product diff

See what changes for the people who use it.

The Product diff states how the product behaves before the pull request and after it, one change at a time.

A brief on every push.

  1. Install the GitHub App

    On the repos you choose. The app is your own, registered by you.

  2. Push

    A push to an open pull request starts a brief. It runs under a daily cap you set. An author outside the team waits for one click.

  3. Open the brief

    A comment on the pull request links to it. Read it before you review the diff.

Already run an AI review bot? Keep it.

It finds problems in the diff.MergeBrief is for what is left after that:the part of review a person still does, and answers for.

No score. No verdict.

Come back to what changed.

Delta Brief
What changed since your last review. Flags you settled stay settled, and reopen if their code changed.
Receipt
What you read and how you handled each flag, with one line of counts on your GitHub review.
Your review on GitHub

Reviewed with MergeBrief: 18/18 chunks read · 7 risks addressed · 1 dismissed · 0 open · 3 inline comments

Revisions
The pull request's revisions, newest first, in the sidebar. Open any one.

Threads, where the code is.

The pull request's GitHub threads sit in the brief, beside the chunks they belong to. Reply and resolve in place. Your bot reviewer's threads are there too, grouped per bot.

Comment on the diff
Start a thread on any line. Post it to GitHub now, or with your review.

Not only a screen. Your agent reads the same brief.

The groups, the risk attributes and the intent check come as JSON, so an AI agent starts from the story of the change and from what matters in it.

CLI

The whole review loop from a terminal, with documented JSON on stdout and exit codes a script can branch on.

npm i -g mergebrief

Skill

Teaches an agent the loop: read the brief, then each group's diff, and hold its findings as private drafts. Nothing is published without your instruction.

npx skills add idan91/mergebrief --skill mergebrief

Your repo, your rules. Teach it your repo.

Files in your repo shape its briefs. They are read from the default branch only, so a pull request cannot loosen its own policy.

Risk policy

Adds your own Risk Surface attributes. Describe each in plain language, and the brief marks the chunks it is true of.

.mergebrief/policy.yaml
version: 1attributes:  touches-billing:    criteria: >      modifies invoicing, payment, or ledger code    implication: needs a reviewer from finance    paths:      - api/billing/**  a11y-surface:    criteria: >      modifies keyboard handling, focus management,      ARIA attributes or roles, or swaps a semantic      element for a less semantic one    implication: >      run the change through the      accessibility checklist    paths:      - src/components/**

Instructions

Your own terms, what belongs in one group, and which paths are noise. Plain text, in your words.

.mergebrief/instructions.md
## Glossary- "stories": Storybook demo files (`*.stories.tsx`).- A component's "API" is its exported props  interface. ## Grouping- A component's `.tsx`, `.scss` and stories are one  review unit. ## Noise- Churn in `*.stories.tsx` is low-signal demo code. ## Reading conventions- `src/types` and `src/utils` come before the  components that use them.

Your model, your tickets, your database. It runs on what you have.

MergeBrief reads your tickets from GitHub, Jira Cloud or Notion, generates with your AI provider, and keeps its records in your own Postgres.

Hold the PR to its ticket.

The intent check reads the ticket a pull request names, and never writes to it.

  • GitHub Issuesbuilt in
  • JiraJira Cloud, with your API token
  • Notionwith your integration token

Bring your own key or sub.

MergeBrief generates briefs with the LLM you already pay for.

API key

Works in the shipped image.

  • Anthropic
  • OpenAI
  • OpenRouter

Subscription

Runs from a source checkout on your own machine.

  • Claudethrough Claude Code
  • ChatGPTthrough Codex
  • Cursorthrough the Cursor CLI

Your code is not stored.

Diffs are read from GitHub for each session and thrown away. Credentials found in a diff are redacted before the prompt reaches your model.

Not stored

  • Your code
  • The pull request's conversation
  • Emails and IP addresses

Stored, in your own Postgres

  • Briefs and their summaries
  • Where each reviewer last reviewed
  • The comments and notes you write
  • Encrypted login sessions

Runs on your infrastructure.

Your model key, your spend. Nothing is sent back to us.

docker compose up -d --wait

Source-available under FSL-1.1-ALv2. Each release becomes Apache-2.0 after two years.

Read the self-host guide

Understand it first. Then review it.