better-diff

diffshub.com is a hosted viewer for public GitHub diffs, built on Pierre's open-source @pierre/diffs and @pierre/trees. It can't reach private repos because it has no way to ask for your GitHub auth.

better-diff packages those same Pierre libraries as a browser extension and adds GitHub Device Flow authentication. You sign in with your own account, the token lives in chrome.storage on your machine, and the viewer reads private repos the same way GitHub does, through the authenticated REST API. Nothing leaves your browser.

The diff viewer itself is entirely Pierre's work. The browser-extension shell, the GitHub API client, and the auth plumbing are the only original parts here.

Docs: nabroleonx.github.io/better-diff

Install

Distribution is via GitHub Releases. No Chrome Web Store or Firefox Add-ons listing, by design (the project is intentionally small and unmonetized).

1. Grab the latest zip from the Releases page.
2. Open chrome://extensions (or edge://extensions).
3. Enable Developer mode.
4. Click Load unpacked.
5. Select the unzipped chrome-mv3 folder.

For Firefox, load firefox-mv2/manifest.json via about:debugging#/runtime/this-firefox.

Setup

Once the extension is loaded:

1. Click the extension icon → Connect GitHub.
2. By default the extension uses a bundled GitHub App Client ID (the one I registered for the project). To use your own instead (for example, to install on an org I don't have access to), open the extension's options page and paste your Client ID before connecting.
3. GitHub shows a one-time code, you approve it. Done.

The Client ID is not a secret. Device Flow doesn't use a client secret, so the bundled ID is committed in the source.

Using your own GitHub App

1. Register a GitHub App (or an OAuth App) with Device Flow enabled.
2. Set repository permissions: Contents read, Pull requests read, Metadata read. Disable webhooks.
3. Install the app on your account or org.
4. Paste the public Client ID into the extension's options page, or build with WXT_GITHUB_CLIENT_ID=<your_id> npm run build.

Development

npm ci
npm run setup        # wxt prepare
npm run dev          # Chrome MV3
npm run dev:firefox  # Firefox MV2

Production builds:

npm run build
npm run build:firefox
npm run zip

Release

Releases are built by GitHub Actions from tags:

git tag v0.1.0
git push origin v0.1.0

The workflow typechecks, audits production dependencies, builds Chrome and Firefox, then uploads the zip files to the GitHub release.

Permissions

Permission	Why
storage	Store the OAuth token when connected, plus UI prefs locally. Never sync.
alarms	Polls the GitHub Device Flow endpoint to complete authentication after the service worker idles out.
sidePanel	Optional side-panel viewer mode.
host_permissions: https://api.github.com/*	Fetch authenticated diff data.
host_permissions: https://github.com/*	Inject the "Open better-diff" button on PR / commit / compare pages; also where the Device Flow endpoints live.

The extension does not request cookies, webRequest, <all_urls>, or declarativeNetRequest.

Privacy

• Token storage defaults to chrome.storage.session (in-memory only, wiped on browser close). better-diff never stores tokens in chrome.storage.sync.
• No telemetry.
• The viewer's CSP locks network access to connect-src https://api.github.com https://github.com. Even compromised code has nowhere to exfiltrate a token.

Dependency updates

Handled by Renovate. Major updates require dashboard approval. Updates are grouped where that keeps review simpler, and automerge is disabled.

Credits

This extension exists because @pierre/diffs and @pierre/trees are open source. The diff renderer, the file tree, the theming, the icons, the truncation primitive: all open-source libraries by The Pierre Computer Company, who also run the hosted diffshub.com that better-diff is modeled on.

better-diff doesn't reimplement any of that. It's a thin browser-extension wrapper that adds GitHub Device Flow authentication and a GitHub API client so the same viewer works on private repos. The project is independent and not affiliated with or endorsed by Pierre.

License

MIT. @pierre/diffs and @pierre/trees themselves are Apache-2.0.