arboretum/packages/desktop/README.md

Arboretum Desktop

Native desktop shell (Electron) for Arboretum. It runs the existing daemon as a child process and shows its web UI in a window, already authenticated (no login screen). The heavy lifting stays in the daemon; this package is a thin shell (window lifecycle, daemon supervision, auto auth).

This package is intentionally outside the root npm workspaces so the daemon CI stays light. It has its own package-lock.json and is built on a developer machine (or a dedicated CI runner), not by the main npm run build.

How it works

1. The shell picks a data directory under the OS user-data path and spawns the bundled Node runtime running the packaged daemon (build/server/package/dist/index.js) with ARBORETUM_EMIT_TOKEN_FD=3.
2. The daemon mints a fresh token and writes {token, url} on file descriptor 3 (private stdio pipe).
3. The shell posts that token to /api/v1/auth/login from the window's session (server to server), which drops the arb_session cookie into the session jar, then loads the SPA on 127.0.0.1.
4. On quit, the daemon child is asked to stop (SIGTERM on POSIX, taskkill /T on Windows, which Windows requires to take the whole process tree down rather than leaving PTY grandchildren behind).

A standalone Node runtime (pinned, >= 22.16) is bundled instead of reusing Electron's Node, so node:sqlite works without a flag and the node-pty prebuild keeps the node. ABI prefix.

Prerequisites (all platforms)

• Node >= 22.16 to build.
• git on PATH at runtime (worktree operations). claude is discovered on PATH or via the in-app Claude CLI setting; it is not bundled.

Develop

cd packages/desktop
npm install            # ELECTRON_SKIP_BINARY_DOWNLOAD=1 to skip the Electron binary if you only typecheck
npm run dev            # bundles main/preload, then `electron .` against the repo's built daemon

npm run dev runs the daemon from the repo (packages/server/dist, so run npm run build at the repo root first) using the system node.

Build installers

Each command builds the shell, prepares the daemon (npm pack + runtime deps with the right node-pty prebuild) and a standalone Node runtime, then runs electron-builder.

npm run dist:linux     # AppImage + .deb  (on Linux)
npm run dist:win       # NSIS + portable  (on Windows)
npm run dist:mac       # dmg + zip        (on macOS)

Artifacts land in packages/desktop/release/.

Linux

Fully supported. dist:linux runs on a Linux host or the Gitea CI runner.

Windows

Must be built on a Windows host. Cross-building from Linux (including via Wine) does not work, and the option has been removed from this document to stop people losing time on it:

• node-pty's check-prebuild.js exits successfully as soon as the host binary exists, so prebuild-install never runs and no win32 binary is fetched (its published tarball only ships prebuilds/linux-*);
• its post-install.js copies conpty.dll and OpenConsole.exe only when the build platform is win32. Without them there is no ConPTY, hence no terminal at all.

In CI this is a dedicated job on a windows-latest runner, enabled by the ENABLE_WINDOWS_BUILD repository variable. Full procedure to register such a runner: docs/CI_RUNNERS.md.

The app requires Windows 10 1809+ (ConPTY). The installer is not code-signed, so SmartScreen shows "unknown publisher": choose "More info" then "Run anyway".

macOS (best-effort)

Build on a Mac (dmg/zip cannot be produced elsewhere); there is no macOS runner, so it is a manual step. The app is not signed or notarized, so Gatekeeper blocks the first launch: right-click the app then "Open", or run xattr -dr com.apple.quarantine /Applications/Arboretum.app.

What the shell adds beyond the window

• Tray icon (src/main/tray.ts): open the window, toggle launch-at-login, quit. On macOS it uses a monochrome template image so it follows the menu-bar theme.
• Application menu (src/main/app-menu.ts): required on macOS, where without it ⌘C / ⌘V / ⌘A are not bound anywhere in the app. Closing the window hides it; app.on('activate') brings it back from the Dock.
• Launch at login (src/main/autostart.ts): a .desktop file under ~/.config/autostart on Linux, app.setLoginItemSettings on Windows/macOS.
• Auto-update (src/main/updater.ts): see below.
• PATH enrichment (src/main/env.ts): a GUI app starts with a minimal PATH. On POSIX we add /usr/local/bin, /opt/homebrew/bin, ~/.local/bin; on Windows %LOCALAPPDATA%\Programs and %APPDATA%\npm, where the Claude CLI and global npm binaries actually live.

Startup, and what happens when it fails

The shell owns the daemon: it spawns it on port 7317 (ARBORETUM_DESKTOP_PORT overrides), waits for the handshake on fd 3, seeds the session cookie, then loads the SPA. Since a fixed port is easy to hold hostage, the port is checked before spawning (src/main/port-guard.ts) and the outcome decides:

Who holds the port	What the app does
Nobody	Starts normally.
Our own daemon, orphaned (its Electron died: crash, kill -9, package upgrade)	Reclaims it: SIGTERM, then SIGKILL, waiting for the port to be effectively free, then starts.
Another live instance of the app	Says so, and points at the tray where that window is hiding. Never kills it.
A third party (arboretum install service, npx @johanleroy/git-arboretum, unrelated software)	Says so, and suggests stopping it or setting ARBORETUM_DESKTOP_PORT.

Ownership is recorded in <userData>/daemon/daemon.json ({pid, ownerPid, port}): a live daemon whose ownerPid is gone is an orphan, one whose owner is alive is another instance. Every failure now opens a dialog with Retry / Show log / Quit instead of quitting silently, and the daemon's output is kept in <userData>/logs/daemon.log. If the daemon dies after startup, the app offers to restart it rather than leaving a dead window on screen.

<userData> is ~/.config/Arboretum (Linux), ~/Library/Application Support/Arboretum (macOS), %APPDATA%\Arboretum (Windows).

Installing a new version

Installers replace the files on disk; they never touch the running process. So after a dpkg -i (or an NSIS run) the open window keeps serving the old version, and its daemon keeps port 7317 - which used to make the freshly installed version unable to start at all.

The recommended order is therefore either one of:

1. Quit Arboretum from the tray, then install, then launch. Clean, nothing to think about.
2. Install while it runs, then click the launcher or the tray icon: the shell notices that its own binary changed on disk (src/main/upgrade-watch.ts) and offers Restart now, which stops the daemon before relaunching, so the new version finds its port free.

Answering Later keeps the old window; the prompt comes back only if yet another version is installed. The check is inert in dev (app.isPackaged is false).

Auto-update

electron-builder emits latest*.yml next to the artifacts and electron-updater reads them from a floating desktop-latest release on Gitea, which the release workflow recreates on every version (that URL is baked into shipped binaries, so it must always exist). Auto-update covers Windows (NSIS) and Linux (AppImage); macOS updates are manual while the app is unsigned.

Bundled Node runtime

scripts/fetch-node.mjs downloads a pinned Node (SHA256 verified) and prunes it to the binary and its licence: headers, docs and npm/corepack are removed, since the daemon's dependencies are installed at build time, never at runtime. That takes the embedded runtime from ~205 MB to ~118 MB.

Icons

Generated by python3 brand/build-assets.py from the source logo, into resources/:

• icons/{16,24,32,48,64,128,256,512}x*.png : the Linux set, at standard hicolor sizes. This is not cosmetic: with a single non-standard size (the old 895×895), the directory is not declared in hicolor/index.theme and the freedesktop spec makes desktops ignore it, so the launcher showed no icon at all.
• icon.png (1024) : macOS source and generic fallback.
• icon.ico : Windows (NSIS installer and window).
• trayTemplate.png (+@2x) : monochrome macOS menu-bar icon.