Architecture overview

Nerve’s main product is a desktop workbench built from an Electron shell, a browser workbench, a local daemon, and shared transport-neutral foundations. The diagrams on this page are generated from the editable sources in the website package’s diagrams/ directory.

System context

The Electron desktop launches or connects to a selected daemon. The browser workbench talks directly to that daemon over authenticated HTTP and Nerve Protocol v1 WebSocket; application data does not flow through broad Electron IPC. The daemon owns the workbench runtime, persistence, tools, model access, and external resource boundaries.

Runtime and daemon ownership

The shell chooses exactly one daemon mode:

adopt a healthy existing local daemon (unowned);
spawn and supervise a local child (owned);
connect to a configured remote daemon (unowned).

Quit stops only the owned child. Existing local and remote daemons are monitored but never spawned or stopped by the desktop shell.

Desktop runtime diagram showing the Electron main process, browser renderer, workbench daemon, existing local daemon, remote daemon, NERVE_HOME, and external services. — Desktop runtime: ownership and monitoring differ for spawned, existing-local, and remote daemons.

The startup path acquires a single-instance lock, prepares the active home, selects the daemon, installs the authenticated browser session, and loads the bundled workbench. Health monitoring can restart only a child owned by this launch.

Sequence diagram showing Nerve desktop startup, legacy-home migration, daemon selection, browser bootstrap, health monitoring, and owned-daemon shutdown. — Startup and shutdown: migration, authentication, recovery, monitoring, and owned-child cleanup happen in order.

Package boundaries

Shared foundations stay transport- and framework-neutral:

@nervekit/contracts owns API, operation, event, policy, tool, model, and storage schemas.
@nervekit/protocol owns the Protocol v1 codec, sessions, RPC, replay, cursors, snapshots, and bounded delivery.
@nervekit/harness owns model resolution, conversation behavior, the generic agent loop, resources, and compaction.
@nervekit/tools owns the canonical tool catalog, executors, output bounds, artifacts, and Git/GitHub utilities.
@nervekit/native provides normalized TypeScript façades over the Rust N-API Git, process, platform, and runtime primitives used by the server.
@nervekit/ui-kit provides contract-free presentation primitives and renderers.

The product hosts compose those foundations:

@nervekit/workbench-server owns HTTP/WebSocket routes, persistence, authentication, runtime composition, process drivers, and the static web host. It consumes @nervekit/native for cross-platform Git and managed-process behavior.
@nervekit/workbench-app owns Svelte presentation and feature adapters/effects.
@nervekit/desktop-shell owns the published launcher, Electron bridge, migration consent/presentation, and daemon ownership; the server package owns storage inspection and migration transactions.

Package dependency diagram showing contracts, protocol, harness, tools, native runtime, and UI kit foundations plus the workbench server, app, and desktop shell hosts. — Package graph: compile-time dependencies are separate from the app-to-server runtime link.

See package responsibilities for the complete ownership map and contributing for repository boundary rules.

State and external boundaries

NERVE_HOME keeps canonical conversation records and durable event streams in SQLite. Complete tool results that exceed the agent preview contract use private owner-scoped files beneath data/conversations/; SQLite records retain their projections, ownership, and integrity references. Electron’s active Chromium profile stays outside the Nerve home so whole-home backup and migration do not capture live browser caches or profile locks. See persistence and security boundaries for storage, secrets, authentication, and migration details.

The server reaches project files and processes locally. Model providers, OAuth, voice transcription, Web and Atlassian integrations, and Git remotes are explicit external paths. Platform reliability documents the native filesystem, process, and desktop-state rules behind those boundaries.

Protocol recovery

Nerve Protocol uses typed RPC plus per-stream cursors, replay, snapshots, and resynchronization. It has no wire-level acknowledgement window; cursor advancement happens after reducers successfully process events. Durable events and transient notifications have different delivery guarantees. Tool output lifecycle explains the same distinction for tool execution and live output.