Forem: Sola Samuel

I built a Chrome extension that explains your console errors in plain English

Sola Samuel — Sun, 10 May 2026 14:13:05 +0000

Here is an error message I got last week:

Warning: Each child in a list should have a unique "key" prop.
Check the render method of `ProductList`.
    at li
    at ProductList (webpack-internal:///./src/components/ProductList.jsx:34:5)

I know what this error means. I've seen it a hundred times. I fixed it in thirty seconds.

Here is a different error I got the same day:

Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'map')
    at processApiResponse (api.js:847:23)
    at async fetchProducts (api.js:112:5)

I did not know what that one meant. Not immediately. The function at line 847 was calling .map() on something, and that something was undefined when it shouldn't have been. But why? Was the API returning a different shape? A race condition? A missing null check upstream?

I spent twenty minutes on that error. I Googled it, read three Stack Overflow answers that all said "just add ?. before the map" — technically correct but doesn't explain why the value is undefined or whether the real fix is somewhere else.

I've been a developer long enough to know what undefined means. The problem was the twenty minutes.

So I built DebugBuddy.

What it does

DebugBuddy is a Chrome extension that captures JavaScript errors from any tab and explains them with the Claude API. Click the extension icon, and the active tab's errors show up in a popup. Click any error, and you get a structured explanation: a summary, the likely cause, a suggested fix, and relevant docs links.

That's the whole product. It is deliberately not a DevTools panel, a content script, or a paste-in-anything tool. The version that ships does one thing — capture errors from the active tab via the Chrome DevTools Protocol and explain them — and tries to do that part well.

The interesting work was not the UI. The interesting work was getting the capture pipeline to behave under a few constraints that are not obvious until you hit them.

Why CDP, not content scripts

The first design question was: how do you actually capture console.error and uncaught exceptions from an extension?

The two viable approaches are:

Content script + document_start injection. Inject a script into the page context that overrides window.console.error before any page code runs. Bridge messages back to the extension via window.postMessage. This is the classic approach and it works, but it has problems: the page can untrap your override, strict CSP can block the injected script, and you're racing against the page's own setup during hydration.

Chrome DevTools Protocol via chrome.debugger. Attach to the tab as a debugger client and subscribe to Runtime.exceptionThrown and Log.entryAdded. This is what DevTools itself uses. It can't be untrapped by page code, isn't affected by CSP, and gives you structured data — a real stackTrace.callFrames array, not a message string you have to re-parse.

I went with CDP. The cost is the yellow "DebugBuddy started debugging this browser" banner Chrome shows whenever a debugger is attached, which is annoying but unavoidable. The benefit is that capture is bulletproof in a way that injection just isn't.

The capture loop is small:

// src/background/index.ts
chrome.debugger.onEvent.addListener((source, method, params) => {
  if (!source.tabId) return;

  let captured = null;
  if (method === "Runtime.exceptionThrown") {
    captured = parseExceptionThrown(params);
  } else if (method === "Log.entryAdded") {
    captured = parseLogEntry(params);
  }

  if (captured) {
    addError(source.tabId, captured).then(async () => {
      const errors = await getErrors(source.tabId!);
      updateBadge(source.tabId!, errors.length);
      chrome.runtime
        .sendMessage({ type: "ERROR_CAPTURED", payload: captured })
        .catch(() => {});
    });
  }
});

That's it for capture. The rest of the work is making sure the debugger session stays attached to the right tabs, doesn't fight with anyone else, and survives Chrome's MV3 lifecycle.

Three constraints that took longer than the feature

1. The MV3 service worker dies. The CDP session doesn't.

In Manifest V3, the background script is a service worker that gets killed after about thirty seconds of inactivity. When it spins back up, every in-memory variable is gone. That includes the Set<number> I was using to track which tabs the extension had attached to.

The wrinkle: Chrome can keep the underlying CDP session alive across a service worker restart. So you wake up, your in-memory attachedTabs says "I'm not attached to anything," and you call chrome.debugger.attach() — which throws, because Chrome thinks you're already attached.

The fix uses two sources of truth and treats Runtime.enable as a probe:

// src/background/debugger.ts
async function isReallyAttached(tabId: number): Promise<boolean> {
  const targets = await chrome.debugger.getTargets();
  return targets.some((t) => t.tabId === tabId && t.attached);
}

async function tryEnableDomains(tabId: number): Promise<boolean> {
  try {
    await chrome.debugger.sendCommand({ tabId }, "Runtime.enable");
    await chrome.debugger.sendCommand({ tabId }, "Log.enable");
    return true;
  } catch {
    return false;
  }
}

getTargets() answers "is anything attached to this tab?" but not "am I the one attached?" The CDP routing rules give you that for free: sendCommand only succeeds for the client that owns the session. If Runtime.enable succeeds, we're the owner. If it throws, someone else is — or the session genuinely doesn't exist.

The full attach logic uses both: if our in-memory set says we're attached, try to re-enable domains; if getTargets() shows something attached but we don't own it, try one more time in case Chrome held our session across the restart; otherwise fall through to a fresh attach() call.

2. There's no API for "is another extension attached?"

Only one debugger client can own a tab's CDP session at a time. If the user has DevTools open, or another debugger extension running, your attach() call fails with a generic "Another debugger is already attached" error.

There is no API that tells you who is attached. chrome.debugger.getTargets() returns an attached: boolean and an extensionId field, but extensionId is empty when native DevTools holds the session, and you can't programmatically distinguish "another extension" from "the user pressed F12."

The workaround is the probe pattern from constraint #1. Try to sendCommand. If it works, we already own the session and the user just opened a fresh popup. If it fails, surface a clean message — "Another debugger is already attached to this tab" — instead of letting the raw exception propagate to the UI.

This came from a real bug. I had a session where DevTools was open in another window, capture silently stopped working, and the only signal was a stack trace in the service worker logs that no user would ever see.

3. Restricted URLs and the auto-attach race

I wanted attaching to be invisible — when you switch tabs, the extension should attach to the new tab automatically so errors are captured from the moment you arrive. Two listeners cover that:

chrome.tabs.onActivated.addListener(async ({ tabId }) => {
  const tab = await chrome.tabs.get(tabId).catch(() => null);
  if (tab && !isRestrictedUrl(tab.url)) attachDebugger(tabId);
});

chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
  if (changeInfo.status === "loading" && !isRestrictedUrl(tab.url)) {
    attachDebugger(tabId);
  }
});

The "obvious" version of this breaks immediately, because chrome.debugger.attach() throws on a long list of internal URLs: chrome://, chrome-extension://, devtools://, about:, view-source:, and a few others. You can't attach to the new-tab page. You can't attach to the extension's own options page. You can't attach to DevTools itself.

The fix is a protocol allowlist checked before every attach attempt:

const RESTRICTED_PROTOCOLS = [
  "chrome://", "chrome-extension://", "edge://", "about:",
  "view-source:", "devtools://", "chrome-search://", "chrome-untrusted://",
];

export function isRestrictedUrl(url: string | undefined): boolean {
  if (!url) return true;
  return RESTRICTED_PROTOCOLS.some((p) => url.startsWith(p));
}

The second half of the fix is in the message handler. When the popup opens on a restricted page and asks the background to attach, returning an error is the wrong UX — there's nothing the user can do about it, and they don't care. So restricted pages return success: true, restricted: true. The popup uses the restricted flag to render a "this page can't be debugged" hint instead of an error.

The smaller details

Deduplication is by message hash. Storage groups errors using a djb2 hash of the message string. If the same error fires twice, the existing entry's count is incremented and the timestamp updated, instead of pushing a new row. A 50-error-per-tab rolling buffer keeps storage bounded.

const existing = errors.find((e) => e.hash === error.hash);
if (existing) {
  existing.count += 1;
  existing.timestamp = error.timestamp;
} else {
  errors.push(error);
}

This is global per tab, not windowed. A render loop firing the same error 50 times per second collapses to a single row with count: 50, which is the behavior I want — render loops should be visible as a high count, not a wall of identical rows.

Explanations are cached for an hour. The cache is keyed by error hash, sits in the service worker's memory, and has a 1-hour TTL. Re-clicking the same error returns the cached explanation instantly without re-billing the API. The cache is wiped on service worker restart, which is fine — the worst case is one extra API call after thirty seconds of idle.

The model is Claude Haiku 4.5. Error explanations are short (a few hundred tokens at most), there's no benefit to a larger model, and Haiku is fast enough that the explanation feels instant when it isn't cached. The system prompt asks for a structured JSON response with summary, likelyCause, suggestedFix, and relevantLinks — which the popup parses into four sections.

It's BYOK. The user's Claude API key is stored in chrome.storage.local and sent directly to api.anthropic.com from the service worker, with the anthropic-dangerous-direct-browser-access header set. Nothing routes through any server I run. The options page validates the key by sending a tiny ping message before saving it.

What I'd build differently

The yellow banner is a tax on every user. Chrome shows "DebugBuddy started debugging this browser" whenever the debugger is attached, and there's no way to suppress it. A future version might detach during long quiet periods and re-attach lazily, but the heuristics are messy — you don't want to miss the first error after a quiet stretch.

Per-tab CDP sessions don't survive navigation cleanly. A full-page navigation can trigger onDetach, requiring a re-attach. The current code handles this via tabs.onUpdated with status === "loading", but it's racy — if the new page throws an error in the first 50ms before re-attach completes, that error is lost. A more robust approach would use webNavigation.onBeforeNavigate to pre-arm the attach.

There's no DevTools panel. A dedicated panel would let users see explanations alongside the Console tab without opening the popup, and it would dodge the yellow-banner problem because DevTools is already attached. It's the most-requested feature and it's on the roadmap.

Try it

Chrome Web Store: [https://chromewebstore.google.com/detail/debugbuddy/cccnbldheilinhcljcmililgalpialig?hl=en-GB&utm_source=ext_sidebar]
GitHub (MIT): [https://github.com/solasamuel/debugbuddy]

You'll need a Claude API key — paste it into the options page once. New Anthropic accounts get a small starting credit; after that, expect a fraction of a cent per explanation at current Haiku 4.5 pricing.

The most interesting file in the repo is src/background/debugger.ts — the attach/probe logic for constraints #1 and #2 is all there in about 100 lines.

The error that started this took me twenty minutes. With DebugBuddy, the same error would take thirty seconds. The twenty minutes wasn't because I'm a bad developer — it was because the tooling made me do unnecessary work.

I'm curious what errors you hit most often. Drop them in the comments — I want to make sure the explanations are good for the errors that matter, not just the ones I happen to encounter in my own work.

I built a browser extension that reviews your PRs before your teammates do

Sola Samuel — Mon, 27 Apr 2026 17:59:05 +0000

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.