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, the generic agent loop, streaming/context primitives, resources and compaction.
@nervekit/conversation-core owns durable conversation history, inputs, tool lifecycle, delegation, async Bash and execution scheduling through host ports.
@nervekit/skills owns built-in skills and harness resource integration.
@nervekit/tools owns the canonical tool catalog, executors, output bounds, artifacts, and Git/GitHub utilities.
@nervekit/native provides TypeScript façades over a Rust N-API addon for Git reads, managed processes, filesystem/Git monitoring, and lexical search indexes.
@nervekit/ui-kit provides contract-free presentation primitives and renderers.

Conversation core does not depend on protocol, workbench-server or UI: the server implements its environment ports. Contracts own domain shapes; protocol owns session and delivery mechanics.

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.

Native computation and responsiveness

Native code owns bounded computation and platform mechanisms, not the agent loop or UI. The server uses createSearchIndex to create a Rust lexical index of typed completion documents, not a file-only completion API. Native code matches terms and returns lexical scores and match ranges; TypeScript providers still own project discovery, permissions, freshness, contextual ranking, and selection effects. Git reads use the native Git domain, while mutations remain Git CLI operations. Managed processes and change monitoring have separate native domains and lifetimes.

Not every performance improvement is a Rust migration. Storage usage accounting scans conversation and log directories once each and reuses their tallies; startup work avoids full-history reads for status and skips creating a migration worker when the migration ledger is validated and current. These are targeted implementation changes, not a claim that the daemon is entirely native or a guarantee of a particular speedup.

The workbench presents background Git operations through header Activity, independently of conversation execution. Tool cards retain a shared lifecycle from streamed arguments through live output and settled results, using bounded previews and on-demand details. See tool output lifecycle for presentation and recovery boundaries.

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.