Desktop app

The desktop app runs the same sketcher as the browser, with native file open/save dialogs, recent files and a local Python server. Python 3.12 or newer and the matching vibesketch package are required. Electron is bundled in a packaged app; Python and RDKit are installed separately.

Install and first run

When a release is available, download its macOS disk image or ZIP from the release’s download links and verify the published checksum. Open the disk image and copy vibe-sketch to Applications, or extract the ZIP and move the app there. Keep the versioned wheel named by that release available for Python setup. See release wheels.

The macOS app is ad-hoc signed, without an Apple Developer ID or notarization. Gatekeeper may block the first launch. If you trust the downloaded artifact and have checked its checksum, use System Settings → Privacy & Security → Open Anyway after the blocked attempt. Follow Apple’s instructions for opening downloaded apps; do not disable Gatekeeper globally.

Open the app from Finder or Spotlight. If no compatible Python environment is found, the setup page explains whether Python itself or the package is missing. Install Python 3.12 or newer if needed, then run the command shown by the page in a terminal. It creates an app-managed virtual environment and installs the wheel matching this desktop version. Select Recheck to continue without restarting the app. A missing wheel or failed package installation must be resolved before the sketcher can start.

The editor waits until its local server is ready. Activating the app or opening a file during setup keeps that file pending; it opens after setup succeeds. If you close the setup window, activating the app opens setup again.

An existing environment can also launch the app through vibe-sketch desktop [FILE]; the CLI records that interpreter for subsequent Finder launches. The app tests that its interpreter can import vibesketch. Keep this environment on the same release as the desktop package; installing a new desktop app does not update an external Python environment for you.

For a source installation, follow the desktop installation instructions. The source launcher follows its checkout and is distinct from a packaged app.

Open, save and recent files

Use File → Open (Cmd+O on macOS), File → Open Recent, a file drop onto the window or Dock icon, or Finder’s Open With → vibe-sketch. A file double-click opens the user’s selected default app; choose vibe-sketch as the default only if that is what you want. The installer offers file types without replacing an existing preferred application.

File type	Desktop association	Behaviour
.vsk	Editor	Open and save a native sketch document.
.qvf	Editor	Import a supported sketch or structure from the archive; saving a calculation result requires another destination.
.mol, .sdf, .rxn, .cdxml, .ket, .xyz	Viewer	Import the supported structure or reaction data into a sketch.

File → Save (Cmd+S) synchronizes the current drawing before writing. Save As (Cmd+Shift+S) selects another destination. A failed export, external file change or cancelled dialog leaves the original file untouched. For an imported or protected QVF, Save opens Save Sketch Copy with a suggested name such as result-sketch.qvf. Choose another destination to keep the original result payloads intact. Cancel leaves the sketch unsaved and keeps its original destination. Selecting the protected original still refuses replacement; subsequent saves use the new sketch copy. Native sketch QVF files save in place. The macOS Open dialog preserves the chosen symbolic-link name, including its extension, while save protection checks the target identity. Open Recent and the document name retain that selected path after opening or saving. Saving QVF needs the optional qvf-writer integration; .vsk works without it. See files in the app and formats.

Open Recent shows up to ten recent paths. Its Clear Recent entry clears the list; it does not delete documents. Missing or unsupported files produce an error without replacing the current drawing.

Settings and local files

Data	Default location
Recent file list	~/.cache/vibe-sketch/recent.json
Interpreter recorded by the CLI	~/.cache/vibe-sketch/interpreter.json
App-managed Python environment	~/.local/share/vibe-sketch/venv
Window state on macOS	~/Library/Application Support/vibe-sketch/window-state.json

XDG_CACHE_HOME replaces ~/.cache, and XDG_DATA_HOME replaces ~/.local/share, when set in the app’s environment. Window state uses Electron’s platform-specific user-data directory. These are settings and environment records, not document storage; documents stay where you save them.

Updates and quitting

Help → Check for Updates checks the packaged app’s update feed. On macOS, the ad-hoc signed app offers a download link; it cannot install an update itself. Quit the app, download and verify the replacement, then replace the Applications copy. Install the matching wheel in the Python environment you use with it. Keep your documents and settings.

For a source checkout, quit the app and run ./scripts/update-desktop.sh from the checkout root. That route updates the environment and browser and refreshes the source launcher. See updating a checkout.

Closing the last window leaves the app running. Choose vibe-sketch → Quit or press Cmd+Q to stop the app and its local server. This does not stop calculations already submitted to an external queue.

Help → Third-party Notices opens the bundled notice index. Packaged apps include browser and desktop dependency notices, Electron and Chromium texts, and the corresponding Indigo and separate InChI source archives. See licensing.

Packaged macOS acceptance

For a release, perform this check on the exact candidate’s unpacked app and on a copy installed from its disk image or ZIP. Use disposable documents and an isolated test profile so existing user settings and file associations are preserved. Record the source commit, artifact checksums, macOS architecture, Python/package versions and the result of each step in the release issue. A source launcher or a successful package build does not establish this check.

1. Build the unpacked app with electron/build-desktop.sh --dir, then the macOS disk image and ZIP with electron/build-desktop.sh. Verify the app signature, version, bundled updater, file declarations and notices. When reusing qualified CI browser assets, keep their exact source identity and run the same packaging and notice checks.

2. Launch without a usable Python environment and confirm the onboarding page. Check both no supported Python and supported Python without vibesketch. Install the exact candidate wheel into the isolated environment, select Recheck, and confirm that the sketcher loads. Public download/bootstrap acceptance also checks the published wheel URL. Exercise activation, tray Show, Open and Open Recent immediately after Recheck, while the backend is starting. No editor or document request should run before the health check succeeds. Repeated activation must still produce only one backend and one editor; a queued file opens when the backend becomes ready. Check failed-startup retry and reopening a closed setup window too.

3. Open a .vsk and a supported .qvf through Finder double-click or explicit Open With. Exercise Open, Open Recent, window drop and Dock drop. Confirm the expected structure each time.

4. Edit and save a .vsk, reopen it and check the edit. Save As to another file. Import a calculation QVF, save the sketch elsewhere, and compare the original QVF checksum. Cancel a save dialog and check the original. Repeat Save As through a .qvf symbolic link whose target has another extension, and through a differently named link to a .qvf target. Protected result bytes must remain unchanged in both cases. A native sketch QVF selected through a link must retain QVF format across Save As, subsequent Save and reopen. Preserve the links themselves.

5. Open Third-party Notices and verify its referenced texts and source archives. Check that the macOS update action offers download/replacement rather than an unusable automatic-install action.

6. Close the window and reopen it; then quit the app. Confirm that its owned server process exits and its listening port closes. Reopen the app and confirm recent files still work. Remove the disposable test profile.

Complete this checklist with observed results before marking packaged desktop acceptance complete. Keep deployment credentials and machine-specific evidence outside product source.

Record failed checks as well as passing ones. If a repair changes the candidate, rebuild and repeat the affected checks on the resulting package; results from an older app do not qualify the corrected artifact. Never replace already published downloads with different bytes under the same version.