Electron Desktop

CLI-JAW is available as a native Electron desktop application. Packaged builds include a Node.js 22 sidecar so the app can run the dashboard server and install a terminal jaw command without requiring a global npm install.

Installation

Download the desktop artifact from the release or manual desktop-release workflow. macOS builds ship as DMG/ZIP, Windows builds ship as NSIS/ZIP, and Linux builds ship as AppImage.

# Build from source:
npm run electron:dist:mac

Bundled Sidecar

The release workflow runs scripts/bundle-sidecar.sh before packaging. The sidecar includes Node.js 24.17, compiled server output, frontend assets, production dependencies, rebuilt native modules such as better-sqlite3, and CLI shims under server/bin/jaw and server/bin/jaw.cmd.

The Electron main process does not import native server modules directly. It discovers the bundled sidecar first, then falls back to a global jaw binary during development.

Panel Layout

The Electron app provides a multi-panel workspace:

Browser Panel

The desktop browser panel uses webview tags for full browsing. Features:

• Tab management (Cmd+T new tab, Cmd+W close tab, Cmd+1-4 switch tabs)
• URL bar with smart input -- URLs navigate directly, search terms go to Google
• Default new tab opens Google
• Local/private hosts are allowed (desktop only -- not available in Web UI)

Diff Viewer

The diff panel shows Git changes for your project:

• Repo root candidates from projectDirs, workingDir, pinned root, home fallback
• Configurable diff settings: root policy, diff mode, base ref, untracked files
• Server-backed API prevents git operations from running in Electron main process
• Path traversal and ref validation guards in diff-service.ts

Keyboard Shortcuts

See the Keyboard Shortcuts reference for the complete list. Key desktop shortcuts:

macOS Permissions

The Electron app may prompt for macOS automation access. Grant it in System Preferences > Privacy & Security > Automation. The app's quit flow is visible and handles cleanup gracefully. Current release artifacts are unsigned and un-notarized, so macOS may require right-click → Open on first launch.

Terminal Command Install

On first launch and from the tray menu, packaged apps can install a terminal jaw command that points at the bundled sidecar shim. macOS installs under /usr/local/bin with an admin prompt when needed. Linux uses ~/.local/bin. Windows PATH registration is handled by the NSIS installer script.

Development

# Run Electron in dev mode (concurrent with jaw server):
npm run electron:dev

# Typecheck/build the Electron app:
npm --prefix electron run build

# Bundle sidecar and create macOS DMG/ZIP:
npm run electron:dist:mac