There's a specific kind of dread that comes with opening a large pull request you've been assigned to review.
You click the link. The diff loads. You scroll. Three hundred changed files. No description. The PR title says "fix stuff." The author is already in another country on a flight.
You've got no idea where to start.
I've been on both sides of this — the reviewer who has to piece together intent from raw diffs, and the author who forgets to explain anything because it all seems obvious from inside the work. After one too many PRs where I spent more time understanding the change than actually reviewing it, I built something to fix the cold-start problem.
It's called GitBrief. It injects an AI-powered sidebar into every GitHub PR page that tells you what the PR does before you read a single line of diff.
The problem with code review as it exists
Code review has a fundamental asymmetry. The author has been inside the problem for hours or days. They know which files matter, which approach they tried first and abandoned, which edge cases they had to handle. The reviewer has none of that. They open the diff cold and have to reverse-engineer the intent from the changes.
This creates three failure modes:
Superficial reviews. Reviewers skim, approve, and move on because the overhead of actually understanding the PR is too high.
Long review delays. PRs sit unreviewed for days because the cognitive cost of starting is high enough that other tasks win the prioritisation battle.
Missed issues. A reviewer who hasn't understood what the PR is trying to do can't evaluate whether it's doing it correctly.
None of this is anyone's fault. It's structural. The tooling doesn't help reviewers orient quickly.
What GitBrief does
When you open a GitHub PR, GitBrief injects a collapsible sidebar that gives you:
- PR Summary — 3-5 sentences on what the PR does and why, streamed progressively as soon as the page loads
- Risk Assessment — flags missing tests, sensitive file changes (auth, .env, payment files), large diff warnings, and anything else worth flagging before you dive in
- Suggested Review Comments — 3-5 specific comments mapped to actual files, not generic advice
- Complexity Score — a 1-10 rating with a short rationale based on lines changed, files touched, number of reviewers, and branch age
- Explain This File — click any file in the diff view to get a plain-English breakdown of what changed in it specifically
The sidebar streams progressively. The summary appears first, then the risk flags, then the suggestions — so you're reading useful context within a few seconds of opening the page, not waiting 15 seconds for a spinner to resolve.
It works on Chrome and Firefox from a single TypeScript codebase.
Building it: the technical problems worth talking about
Most of the extension logic is straightforward. The interesting parts are three specific challenges that look easy until they aren't.
1. GitHub doesn't reload pages between PRs
GitHub uses Turbolinks-style navigation. When you click from one PR to another, the page doesn't do a full reload — it swaps the content via JavaScript. This means a naive document.ready event listener fires exactly once and then never again.
The extension needs to detect every PR page navigation, not just the first one, and re-inject the sidebar each time. It also needs to remove the previous sidebar before injecting a new one, or you end up with duplicates.
The correct approach is a MutationObserver on document.body watching for childList changes, combined with intercepting the browser history API:
const originalPushState = history.pushState.bind(history);
history.pushState = (...args) => {
originalPushState(...args);
handleNavigation();
};
window.addEventListener('popstate', handleNavigation);
const observer = new MutationObserver(() => {
if (isPRPage() && !sidebarExists()) {
injectSidebar();
}
});
observer.observe(document.body, { childList: true, subtree: true });
The isPRPage() check uses URL pattern matching (/^\/[^/]+\/[^/]+\/pull\/\d+/). The sidebarExists() check prevents duplicate injection when the observer fires multiple times during a single navigation.
I spent longer than I'd like to admit getting this right. The MutationObserver fires a lot — GitHub makes dozens of DOM changes during navigation — so the callbacks need to be cheap and idempotent.
2. Large diffs will eat your API budget
GitHub PRs can have diffs with 50,000+ lines across hundreds of files. Sending everything to Claude is both expensive and slow.
The chunking strategy has three layers:
File prioritisation. Not all files are equally important to review. The extension sorts files before sending them to Claude:
- Auth files, env files, payment-related files → highest priority
- Core business logic → high priority
- Tests → low priority (important, but a missing test shows up in the risk assessment)
- Config files, package.json → lowest priority
Truncation. Any file over 400 lines is truncated to its first 200 lines and last 200 lines, with a [N lines truncated] marker in the middle. For most files, the beginning and end contain the information you need — the class/function signatures, the main logic, and the return values.
Two-pass approach for very large PRs. For PRs that are still too large after truncation:
- Send the file list only (names, sizes, types) and ask Claude which files are most worth looking at
- Send only those files in full
This keeps costs predictable and response times under 10 seconds for almost any PR.
Results are cached in chrome.storage.session keyed by {owner}/{repo}/{pr}/{commit_sha}, so navigating back to a PR you've already analysed is instant.
3. Streaming from a background service worker to a content script
The Claude API supports Server-Sent Events for streaming responses, which is how the sidebar updates progressively. But there's an architectural wrinkle: in a browser extension, the Claude API call happens in the background service worker (which has network access), and the sidebar UI lives in the content script (which doesn't). You need to relay the stream between them.
chrome.runtime.sendMessage is one-shot — you send a message, you get a response, connection closes. That doesn't work for a stream.
chrome.runtime.connect creates a long-lived port that stays open, which is what you need:
// In the content script — opens a port to the background worker
const port = chrome.runtime.connect({ name: 'analysis-stream' });
port.onMessage.addListener((message) => {
if (message.type === 'chunk') {
appendToSidebar(message.content);
}
if (message.type === 'done') {
port.disconnect();
}
});
port.postMessage({ type: 'analyse', diff: extractedDiff });
// In the background service worker — relays SSE chunks to the port
chrome.runtime.onConnect.addListener((port) => {
port.onMessage.addListener(async (message) => {
if (message.type === 'analyse') {
const stream = await anthropic.messages.stream({ ... });
for await (const chunk of stream) {
port.postMessage({ type: 'chunk', content: chunk.delta.text });
}
port.postMessage({ type: 'done' });
}
});
});
The sidebar renders summary, risk, and suggestions as separate sections, so each one can appear as soon as Claude has finished generating it — the user is reading the summary while the risk assessment is still being generated.
The thing about building for GitHub specifically
One thing I didn't anticipate: GitHub's UI is very... opinionated about external injections. The extension has to be careful not to interfere with existing event handlers, not to pollute the global namespace, and not to add layout that breaks GitHub's responsive behaviour.
The sidebar is absolutely positioned relative to the viewport, not the PR content area, so it doesn't affect the diff layout. It's also collapse-by-default on mobile-width viewports so it doesn't eat the screen.
There's also the question of keeping up with GitHub's DOM changes. They ship UI updates regularly and don't publish a changelog for their HTML structure. The extension uses structural selectors and data attributes rather than class names (which GitHub obfuscates) wherever possible, but you still need to test after major GitHub UI updates.
What's next
The v1 feature set covers the core use case. The v2 roadmap I'm thinking about:
Review checklist — per-repo customisable checklist injected into the sidebar. "Did you update the docs?", "Is there a migration script?", "Have you tested on staging?" — the things teams always forget to check.
Stale PR detector — badge the PR list view with age warnings for PRs that have been open longer than a team-defined threshold. PRs that sit too long tend to get merged with less scrutiny, not more.
Team mode — shared review templates and history across an org, so teams can build up a library of common review patterns.
Try it
Chrome Web Store: [https://chromewebstore.google.com/detail/ikifklfoigcncmigejeamnlopbhlbefh?utm_source=item-share-cb]
GitHub: [https://github.com/solasamuel/gitbrief]
You need a Claude API key — enter it once in the settings popup and it persists across devices. The free tier handles most PRs without any cost.
The code review cold-start problem is real and fixable. I've been using GitBrief on my own workflow for a few weeks now and it's changed how I approach large PRs — I read the sidebar first, then go to the files I actually need to look at, rather than scrolling the entire diff trying to build a mental model.
If you build something on top of it or find a bug, open an issue. And if you have opinions about what v2 should prioritise, I'd genuinely like to know — drop them in the comments.
Top comments (0)