SnappyRef

A local reference-board app for macOS and Windows. Drop images on a canvas, arrange them, and find them again across every board with on-device search.

What it does

• Boards. Each named Board keeps its own placements, annotations, groups, viewport, background, and undo history.
• Import. Drag files or browser image URLs onto the canvas, or paste. On Windows, pasting PureRef clipboard content imports the images it references.
• Formats. JPEG, PNG, WebP, GIF, TIFF, BMP, SVG, OpenEXR, and JPEG XL on both platforms. macOS also decodes AVIF, HEIC, PSD, and JPEG 2000 through the system decoders.
• Editing. Move, resize, uniform scale, rotate, crop, duplicate, group, change stack order, and draw arrows, lines, and textboxes.
• Layout. Snapping guides, compact, row, and column arrange, group auto-layout, and a configurable gap between placements.
• Library. Every imported image lands in one local Library shared by all boards. Exact duplicates reuse the existing Asset.
• Semantic Search. Optional. Cmd+F (Ctrl+F) searches the whole Library by text or by an image, and results drag straight onto the board.
• Shortcuts. Every action has a key. The sidebar (Cmd+B / Ctrl+B) lists them and holds settings, boards, and the app version.
• Updates. The app checks a signed release manifest and installs newer versions itself. Your Library and model files stay put.

Download

Releases are at https://github.com/noelcserepy/snappyref/releases. Each release has snappyref-mac-<version>.zip and snappyref-windows-<version>.zip. Unzip, keep the SnappyRef folder together, and run the app from inside it. The Library is stored beside the app when that folder is writable, otherwise in your user app-data directory.

First launch:

• macOS 14 or newer. The app is ad-hoc signed, not notarized, so a plain double-click is blocked. Try opening SnappyRef.app, then go to System Settings > Privacy & Security and click Open Anyway. Confirm Open when prompted. See Apple's instructions.
• Windows. The exe is unsigned. SmartScreen shows "Windows protected your PC". Click More info, then Run anyway.

After that, updates arrive in-app. The app verifies latest.json against an embedded ed25519 public key before it downloads or installs anything.

Semantic Search

Off until you enable it. The app asks once on first launch, and Settings in the sidebar can turn it on later. Enabling downloads one model package, about 254 MB, from the releases page. The model is SigLIP2 (onnx-community/siglip2-base-patch16-224-ONNX, int8) and runs on-device through ONNX Runtime. Queries and embeddings never leave your machine. The model lives in a models/ folder next to the Library, and app updates do not touch either.

AI control

Off until you turn it on. In the sidebar open Settings, General, AI control and choose a level:

• Ask. AI clients on this computer can read and edit your boards. You confirm in the app before they remove library images or change the search model.
• Full. Nothing asks.

Then press Copy MCP config and paste it into your AI client's MCP settings. It looks like this, with the path to your install:

{
  "mcpServers": {
    "snappyref": {
      "command": "/Applications/SnappyRef.app/Contents/MacOS/snappyref",
      "args": ["--mcp"]
    }
  }
}

The client starts snappyref --mcp, which talks to the running app and starts it behind your other windows when it is closed. There are 19 tools. get_board returns the open board as JSON and edit_board applies a batch of edits as one undo step. The rest cover boards, image import, library search, the view, selection, screenshots, PureRef export and settings. The app listens on 127.0.0.1 only, and a client needs the token in control.json inside your Library folder.

Build from source

You need Rust stable and a C compiler. SQLite is compiled from source by rusqlite and ONNX Runtime is fetched as a prebuilt binary by ort during the build. The default turbojpeg-native feature links libjpeg-turbo for fast JPEG decoding, and that is the one library you install yourself.

macOS. .cargo/config.toml sets TURBOJPEG_SOURCE=pkg-config, so the Homebrew package is enough:

brew install jpeg-turbo pkg-config
cargo build --locked --release

Windows. Either install libjpeg-turbo through vcpkg and point the build at it, the same way the release workflow does:

vcpkg install libjpeg-turbo:x64-windows-static-md
$env:TURBOJPEG_SOURCE = "explicit"
$env:TURBOJPEG_STATIC = "1"
$env:TURBOJPEG_LIB_DIR = "<vcpkg root>\installed\x64-windows-static-md\lib"
$env:TURBOJPEG_INCLUDE_DIR = "<vcpkg root>\installed\x64-windows-static-md\include"
cargo build --locked --release

or skip it with cargo build --locked --release --no-default-features. JPEGs then decode through the pure-Rust image crate, which is slower on large files.

Linux is not a supported target today. Nobody builds or tests there.

To run a development build without touching a real Library, give it its own data directory:

SNAPPYREF_DATA_ROOT="$(mktemp -d)" cargo run --locked --bin snappyref

Development checks

Point git at the repo hooks once per clone:

git config core.hooksPath .githooks

The check policy owns the commands run by the pre-push hook and CI. It also explains inspect scenarios and Windows checks.

Code map

AGENTS.md has the process model, the module map, and the repo rules.

Issues

Found a bug or want a feature? Open an issue. I don't accept pull requests.

License

MIT. See LICENSE.

Third-party licenses are in THIRD_PARTY_NOTICES.txt, next to snappyref.exe on Windows and in SnappyRef.app/Contents/Resources on macOS.