Clara is a cross-platform background removal application built with Wails. It combines a native Go backend with a React (Vite) interface and supports multiple “engines” (local ONNX Runtime presets, optional RMBG-2.0, and an IMG.LY Web engine).
- Queue UX: virtualized queue list (handles large batches), per-item preview, keyboard shortcuts, onboarding modal.
- Multiple engines: local ONNX Runtime engine (preset-based models like U²‑Net / BiRefNet), RMBG‑2.0 engine, and optional IMG.LY Web engine (WASM, consent-gated).
- Output modes + formats: cutout/mask/composite; outputs in PNG/JPG/WebP (mask forces PNG).
- Optimisation pipeline: optional post-processing via built-in and external optimizer tools (installable per platform; format/mode aware).
- Automation + file ops: folder watch + auto-import, deterministic destination naming with duplicate handling, optional timestamp preservation, “Reveal in Explorer/Finder”.
| Platform | Minimum | Notes |
|---|---|---|
| macOS | 11 Big Sur | Apple Silicon & Intel supported |
| Windows | 10 (19045) | WebView2 runtime must be present |
| Linux | Ubuntu 22.04 / Fedora 38 | libwebkit2gtk (Wails dependency) |
| Toolchain (dev/build) | Go 1.22+, Node 22+, npm 10+, Wails CLI |
.
├── backend/ # Go backend (config, filesystem, Wails bindings)
├── pkg/ # Go domain packages (engine, models, imgly, optimizers)
├── frontend/ # React UI (Vite + Vitest)
├── assets/ # Source assets (manifests, optimizer binaries, optional IMG.LY bundle)
├── scripts/ # Unified cross-platform Node.js scripts (fetch/build/package/clean)
├── build/ # Generated outputs (ignored except a few Wails metadata files)
├── main.go # Wails application bootstrap
└── wails.json # Wails config (frontend embed, app metadata)
- Repo
assets/: source inputs for building (manifests + optional bundled assets). build/bin/: build output folder (containsclara.exe/.appand staged runtime payload).build/cache/ort/<platform-arch>/: download cache for ONNX Runtime libraries (not shipped directly).- Runtime payload:
build/bin/assets/…(what the packaged app reads at runtime).
Use the bootstrapper to get a fresh machine ready (downloads runtime deps and installs JS/Go deps):
node scripts/ensure-deps.mjs --accept-license --imgly-modelsNotes:
--accept-licenseis required to download IMG.LY assets (AGPL). If you don’t want IMG.LY, add--skip-imgly.- On Windows, this script can also try to install packaging tools (NSIS/WiX) via
winget(best-effort).
Start dev mode:
wails devThis runs the Go backend and proxies the Vite dev server.
Build the app and stage runtime assets into the output folder:
node scripts/build.mjs --preset community
node scripts/build.mjs --preset personal- community: ships manifests and runtime libs, but does not bundle user model weights and does not bundle IMG.LY by default.
- personal: bundles your user-installed model weights + user IMG.LY assets (if present).
- none: minimal baseline; you explicitly enable bundling with
--bundle-*flags.
--bundle-config: use your current userconfig.jsonasassets/defaults.json(bundled defaults)--bundle-defaults/--no-bundle-defaults: include/omitassets/defaults.json--bundle-models/--no-bundle-models: include/omit user-installed ONNX weights--models <comma-separated preset IDs>: restrict which user-installed weights to bundle--bundle-imgly/--no-bundle-imgly: include/omit IMG.LY bundle--imgly-source user|repo: bundle IMG.LY from user install or from repoassets/imgly--bundle-optimizers/--no-bundle-optimizers: include/omit optimizer binaries (manifest is always included)--bundle-ort/--no-bundle-ort: stage/remove ORT shared libraries beside the binary
Preview the effective plan without building:
node scripts/build.mjs --preset personal --bundle-config --dry-runPackaging outputs are written to:
build/packages/<platform-arch>/
Examples:
# Portable only
node scripts/package.mjs --preset personal --outputs portable
# Portable + Windows installers (run on Windows + tools installed)
node scripts/package.mjs --preset personal --outputs portable,nsis,msiWindows notes:
- NSIS installer defaults to per-user install under
%LOCALAPPDATA%\Programs\Clara(no admin). - Use
--install-scope machinefor a machine-wide install (Program Files, admin required).
npm run clean:buildOptional:
node scripts/clean-build.mjs --packages(remove packaged artifacts)node scripts/clean-build.mjs --assets(remove staged runtime payload underbuild/bin/assets)node scripts/clean-build.mjs --caches(remove ORT caches underbuild/cache/ort)
Backend uses os.UserConfigDir()/clara/... (lowercase clara):
| Platform | Base dir (os.UserConfigDir()) |
Clara user dir |
|---|---|---|
| Windows | %APPDATA% |
%APPDATA%\clara\ |
| macOS | ~/Library/Application Support |
~/Library/Application Support/clara/ |
| Linux | $XDG_CONFIG_HOME or ~/.config |
~/.config/clara/ |
Important subfolders:
config.json(settings)models/(installed ONNX weights)imgly/(installed IMG.LY bundle)
- Config: backend loads config in layers: hardcoded defaults → bundled
assets/defaults.json→ userconfig.json. - Models:
assets/onnx-models/manifest.jsondefines available presets; weights are downloaded into the user directory after consent; personal builds can bundle them intobuild/bin/assets/onnx-models/. - IMG.LY: installed into the user dir and optionally bundled into
build/bin/assets/imgly/. - ORT: downloaded into
build/cache/ort/<platform-arch>/and staged beside the binary (onnxruntime*.dll/.so/.dylib) for reliable dynamic loading. - Frontend: React UI calls backend via Wails bindings (
frontend/wailsjs/...) for config, install/uninstall, and processing.
go test ./...
cd frontend
npm testMIT License - Copyright (c) 2025 Leeroy Brun