Desktop App

The Electron desktop app is the primary Neon Pilot operator UI. It hosts the React renderer, manages the local daemon lifecycle, and provides the full feature surface.

Starting

# Stable production build
pnpm run desktop:start

# Development mode with hot reload
pnpm run desktop:dev

# Demo mode with seeded data
pnpm run desktop:demo

Both desktop:start and desktop:dev build the Electron shell and launch it through packages/desktop/scripts/launch-dev-app.mjs.

For packaged builds, launch Neon Pilot.app from the output directory. RC builds launch as Neon Pilot RC.app so they can coexist with the stable app.

Runtime Model

Electron main process
    │
    ├── Renderer (React) ── neon-pilot://app/
    │       │
    │       ├── Conversation routes
    │       ├── Knowledge
    │       ├── Automations
    │       └── Settings
    │
    ├── Backend child process
    │       │
    │       ├── Local API
    │       ├── Session parsing and search
    │       ├── Git/checkpoint operations
    │       ├── Knowledge base reads/writes
    │       ├── Extension backend host
    │       └── Daemon runtime
    │             │
    │       ├── Scheduled tasks
    │       ├── Wakeups
    │       └── Follow-up queue

• Electron owns the UI surface through the neon-pilot://app/ protocol
• Keep the startup path tiny: the main-process hot bundle should only create the window, register protocol/IPC, and schedule deferred work
• Freeze-prone local API work runs in the backend child process; do not import or execute heavy desktop server capabilities directly on the Electron main thread
• Avoid spawnSync/execSync in desktop main-process flows
• The daemon owns durable background behavior inside the backend child and starts after the renderer has had a chance to paint; user actions that need it can force-start it immediately
• The desktop app loads initial readonly snapshots first, then connects to server-pushed events for conversations, executions, automations, and daemon status after startup settles

Layout

Toggle the left sidebar with Cmd+/ (or Ctrl+/). Toggle the workbench with Cmd+\ (or Ctrl+\).

Workbench Tabs

The workbench new tab page includes:

Knowledge is also a primary left-sidebar page. Extension-contributed workbench tools can appear on the new tab page. Tabs are context-sensitive; artifacts open from transcript cards and do not appear as a generic new-tab option. Checkpoint diffs and background work render inline in the transcript. Heavy workbench panels are lazy-loaded so they do not inflate the initial renderer bundle.

Keyboard Shortcuts

Desktop menu shortcuts are configurable in Settings → Desktop. Host and extension command keybindings are configurable in Settings → Commands. Defaults:

Routes

Demo Mode

pnpm run desktop:demo creates an isolated temporary state root with seeded conversations, automations, executions, and assets for UI development and testing. Seeded content includes conversations with artifacts, checkpoints, reminders, subagent demos, and pathological fixtures.

Edit this page on GitHub →