Building from source
How to clone, build, and run OpenWaggle from source.
Build OpenWaggle from source when you want to investigate a bug or try a local change. If you only want to use the app, follow Installation instead. You can send a fix as a pull request. Read Contributing for the CLA and the process.
Install the tools
You need:
- Git.
- Node.js 24. The root
package.jsonaccepts>=24 <25. - Bun, at the version in the
packageManagerfield of the rootpackage.json(also in.bun-version).
Use Bun for every command in this repository. Bun installs the dependencies, runs the scripts and runs the tests (bun --bun vitest). Node.js runs the Electron build tools and the native module builds. Some dependencies are native modules that must be built for the runtime that loads them. The development and build scripts prepare the Electron builds for you.
OpenWaggle builds the native modules better-sqlite3 and node-pty from source, so you also need a C++ toolchain and Python 3. On macOS, the Xcode Command Line Tools provide both. On Linux, install your distribution’s compiler packages, such as build-essential and python3 on Debian and Ubuntu.
Windows
On Windows, install Build Tools for Visual Studio 2022 from the Visual Studio older downloads page, or download the 2022 installer directly. The main downloads page offers Visual Studio 2026, which OpenWaggle hasn’t been tested with. In the installer, select:
- The Desktop development with C++ workload. Both native modules need it.
- On the Individual components tab, MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest). Its component ID is
Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre. Without it, buildingnode-ptyfails with errorMSB8040.
You also need Python 3. If neither python --version nor py --version prints a Python 3 version in a new terminal, install it from python.org. The build finds Python through either command.
Check that bun --version works in a new terminal. If you installed Bun with npm install -g bun and Windows can’t find bun, run npm prefix -g and add the folder it prints to your user Path environment variable, then open a new terminal.
Clone and install
Run these together to get the source and its dependencies:
git clone https://github.com/OpenWaggle/OpenWaggle.git
cd OpenWaggle
bun install
The first install downloads several large packages, and Bun retries a download that fails. If bun install still fails on a slow connection, run it with fewer downloads at once:
bun install --network-concurrency 3
Run the app in development mode
bun run dev
This opens the Electron app with hot reload for the UI, on macOS, Windows and Linux. Changes to the main process or the Session Host may need a restart. Connect a provider and open a project as described in Get started.
A development build is a Dev build with its own app data folder, named after your Git branch. Environment variables lists the variables that change this.
Run the app hidden for automated QA
bun run dev:debug
bun run dev:debug runs the app in a hidden window for automated Electron QA. The window never appears or takes focus. It uses a temporary profile with its own home folder and Pi agent folder, a mock keychain, and the Chrome DevTools Protocol on port 9223. It starts none of the MCP servers in the project’s MCP files, and it stops the app’s Session Host when it stops. Follow .agents/skills/electron-qa/SKILL.md when you use it. Agents must not run the visible debug command, bun run dev:debug:headed, unless the maintainer approves that exact run.
Build the app
bun run build
This builds the application bundle. It does not create an installer.
Build an installer
Each platform has its own command. Run the one you need.
A macOS .dmg for the architecture of the Mac you build on:
bun run build:mac
macOS .dmg files for both arm64 and x64:
bun run build:mac:all
A Windows NSIS installer for x64:
bun run build:win
A Linux AppImage for x64:
bun run build:linux
On Apple silicon, test the arm64 DMG or dist/mac-arm64/OpenWaggle.app. The x64 app in dist/mac/ runs through Rosetta, so it is only useful for checking Intel compatibility.
Check your changes
Start with the checks that matter for most changes:
bun run typecheck
bun run lint
bun run test:unit
Add bun run test:integration when the change crosses services, and bun run test:component when it changes UI components. .agents/verification.md has the full list of checks and when to run each one.
The test scripts build the native dependencies for Node.js. bun run dev builds them for Electron again, so you can switch between the two without doing anything by hand.
For where code lives and which parts may import what, see Architecture.