Self-Review With AI Before You Open the PR — A Practical Workflow with branchdiff

You know the moment. You push the branch, open the PR, and immediately see it — the undefined return on the refund path, the token logged to the console, the TODO that was supposed to be temporary six weeks ago. The reviewer catches it four hours later and you reply "good catch, fixing now" as if someone else wrote that line.

The first reviewer on most pull requests should have been the author. Half the comments you will receive — the missing null check, the untested error branch, the duplicate logic that could be extracted, the import that now goes nowhere — are things you would have caught with one more careful read-through. You skip that read because you have been in the code for two days and your brain completes the sentences for you. You see what you meant to write, not what is on the page.

This post is about closing that gap with a structured AI-assisted self-review before the PR opens. Not to skip the human reviewer — to walk into the review with the obvious problems already gone, the test gaps already filled, and the PR description already written. So the reviewer's attention can land on what actually needs a second pair of eyes.

The tool is branchdiff: a local browser app that runs your diff on localhost, stores everything in ~/.branchdiff/, and keeps the AI surface controlled through an explicit branchdiff agent command API. Nothing leaves your machine until you decide to push it.

Why "before the PR" is the right moment

Step 1 — open your own diff locally

branchdiff main feature/payments

A browser tab opens at http://localhost:5391. Because you are comparing two named refs, this is a persistent session — comments you (or the AI) post here survive new commits to either branch. You can iterate across multiple rounds of fixes without losing the review trail. If you want a fresh start, --new archives the current session and creates a clean one; archived sessions stay queryable via branchdiff review threads --session <id>.

The diff renders with split or unified view, syntax highlighting for 150+ languages, a sidebar of changed files, and keyboard shortcuts (j/k for next/previous file, n/p for next/previous hunk).

Step 2 — run an AI review pass

If you use Claude Code, install the skills once:

branchdiff skill add        # adds .claude/skills/branchdiff-{review,resolve}

Then in your Claude Code session:

/branchdiff-review main feature/payments

The skill calls branchdiff agent diff to read the full diff, then posts inline comments via branchdiff agent comment --file <path> --line <n> --body "[tag] ...". Each comment carries a severity tag:

Two [must-fix] items, three improvements, one nit to dismiss, one question to answer. Twenty minutes of cleanup. The PR you push is materially better than the one you would have pushed before lunch.

The AI's general comment often summarises the change set in two or three sentences ready to paste into the PR description — that alone saves five minutes of staring at the PR form wondering how to explain what you did.

And the dismissal trail matters beyond this session. When you dismiss the [nit] with reason "team style is mixed casing for legacy enums — see ADR-014", that reason is on record. The next engineer who reads src/types.ts and wonders about the inconsistency has an answer one branchdiff session away.

Where to stay skeptical

AI is fallible. It will flag non-issues and miss real bugs. The most common failure mode is confident-sounding wrong advice on async code — read those comments twice.

Local context only. The AI sees the diff and the files in your repo. It does not see runtime behaviour, production logs, or upstream service contracts. Those still need a human reviewer or an integration test.

Token budget. For a 200-file refactor, point the AI at the riskiest ten files first — you can always run a second pass with a different focus.

Do not auto-resolve everything. /branchdiff-resolve is convenient, but read the patches before committing. The AI will occasionally "fix" something by deleting code instead of correcting it.

The AI does not replace understanding your own change. If you do not understand a chunk of code well enough to review it, no AI pass magically fills that gap.

Ship the PR

When the session is clean — open count at zero, threads resolved or dismissed with reasons attached — commit your fixes, squash any fixup! commits, and push. Either open the PR on the platform or use the Open a Pull Request button in the branchdiff toolbar (it appears automatically when no PR exists for the branch). The local session stays in ~/.branchdiff/ for your own reference; nothing from the AI pass needs to land on the PR unless you explicitly push it.

The reviewer who picks it up sees a tighter diff, fewer obvious bugs, a clearer description. Their attention can land on the parts that need real judgement: the architectural decision, the unclear contract, the edge case that matters in production but not in tests.

Quick start

Full install guide, changelog, and uninstall steps on the