Install

Three ways in, in increasing order of effort — one npx line for the command line, a dmg for the app, or a build from source. The dmg is unsigned, so macOS refuses to open it on the first attempt; here is exactly how to open it anyway, and exactly what that means.

Getting startedEdit this page

The fastest way in: the command line#

No download and no Gatekeeper detour. If you have Node 22.12 or newer:

One comparison, nothing installedbash

npx twinscope before.json after.json

That runs the same sixteen engines the app runs, on the same detection, and prints what changed. Install it properly with npm install -g twinscope. It is one bundled file with zero dependencies and no native modules, so there is nothing to compile and nothing to go wrong on your machine — the full reference is the twinscope command line.

The desktop app is the better tool for reading a diff — the tree, the image modes, the change navigation. The command line is the better tool for answering a question quickly, or for CI.

Requirements#


macOS	The primary target for the app. Both Apple silicon (`arm64`) and Intel (`x64`) dmgs are built.
Node	22.12 or newer to run the command line. 24 (LTS) to build from source — `nvm use` picks it up from `.nvmrc`.
npm	11 or newer, which ships with Node 24.
Windows / Linux	An NSIS installer, an AppImage and a `.deb` are published, but they are untested on their own platforms. The command line runs anywhere Node does.

Download the macOS build#

The dmg is published on GitHub Releases — see Download for the current file. Open it and drag TwinScope to your Applications folder.

Then read the next section before you double-click it, because double-clicking will not work.

macOS will refuse to open it#

To open it anyway:

Open your Applications folder in Finder.
Right-click (or Control-click) TwinScope.
Choose Open from the context menu.
In the dialog that appears, click Open again.

That is the whole workaround, and it is needed once. After that the app launches normally from Spotlight, the Dock or a double-click.

What you are doing when you click that second Open is telling macOS that you vouch for this binary. That is a real trust decision, not a formality. If you would rather not make it on our behalf, build from source — the result is the same app, built by you.

Build from source#

Terminalbash

git clone https://github.com/codeAesthetic/twinscope.git
cd twinscope

nvm use # or: nvm install 24 — the version comes from .nvmrc
npm install # also fetches the Electron binary, see below
npm run dev # opens the app with hot reload

That is the whole setup. To produce a dmg instead of a dev window:

Terminalbash

npm run package:mac   # -> release/TwinScope-<version>-arm64.dmg, plus x64 and zips

Command	What it does
`npm run dev`	Electron and Vite with hot reload
`npm run build`	Production build into `out/`
`npm run package:mac`	Builds the dmgs and zips into `release/`
`npm run gate`	Typecheck, lint, format check, unit tests and the regression suite, in the order CI runs them

Where TwinScope keeps its files#


Comparison history	`twinscope.db` in the app's user-data directory — on macOS, `~/Library/Application Support/TwinScope/`
Preferences and window geometry	`settings.json`, in the same directory
Exported reports	Only where you choose them in the save dialog

Deleting that directory resets the app to a first-run state. Nothing else on your system is touched — see Privacy.

Next#

Run your first comparison.