Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
Nudge (also referred to as OpenLive) is a low-latency, AI-powered study tutor designed to observe a student's screen and provide targeted, Socratic guidance. The project is built as a monorepo containing a Next.js web interface, an Electron desktop shell, and a WebSocket-based agent service. By running models like Whisper and Kokoro on-device via WebGPU, Nudge minimizes latency and eliminates cold starts.
Sources: CONTRIBUTING.md:1-5, apps/desktop/README.md:1-8, services/agent/src/prompt.ts:4-15
Development Environment Setup
To begin contributing to Nudge, you must ensure your environment meets the minimum engine requirements and has the necessary package management tools installed.
Prerequisites
- Node.js: Version 22.13 or newer.
- Package Manager:
pnpm(version 11.5.2 is pinned in the root configuration).
Sources: CONTRIBUTING.md:8-10, package.json:8-11
Initial Installation
Clone the repository and install dependencies from the root directory:
pnpm install
Sources: CONTRIBUTING.md:12, apps/desktop/README.md:12
Project Architecture
The project is structured into distinct packages and applications to separate the UI, the agent logic, and shared utilities.
| Directory | Component | Description |
|---|---|---|
apps/desktop | Electron Shell | Manages local servers, system permissions, and the native window. |
apps/web | Next.js UI | The frontend interface including the on-device voice engine. |
services/agent | Agent Server | Handles the /live WebSocket connection and model tool execution. |
packages/harness | Model Adapters | Integrations for Anthropic, OpenAI Chat, and model listing. |
packages/shared | Shared Logic | Contains the wire protocol and shared TypeScript types. |
packages/db | Data Store | JSON-file storage for API keys, settings, and conversations. |
Sources: CONTRIBUTING.md:21-30, apps/desktop/README.md:65-70
System Data Flow
The following diagram illustrates the interaction between the Electron shell, the local services, and the external AI providers.
The voice loop (VAD, STT, end-of-turn, TTS, barge-in) resides in the web application, while model turns are orchestrated by the agent service.
Sources: CONTRIBUTING.md:31-33, apps/desktop/README.md:65-70
Running the Application
Nudge supports multiple execution modes depending on the development focus.
Desktop Development
To run the full desktop experience (including web and agent servers inside the Electron window):
pnpm desktop:dev
This script sets specific ports: 47823 for the agent and 47824 for the web server to avoid local collisions.
Sources: CONTRIBUTING.md:13, apps/desktop/README.md:17, package.json:16
Web-Only Development
If you are only working on the UI or agent logic without the desktop shell:
pnpm dev
This starts the web server on http://localhost:3000 and the agent on the default port.
Sources: CONTRIBUTING.md:17-18, package.json:13
Core Features and Interaction
Live Session Management
The useLiveSession hook orchestrates the voice-driven tutoring sessions. It manages the lifecycle of on-device AI models, microphone streams, and camera/screen captures.
Development Commands
| Command | Action |
|---|---|
pnpm typecheck | Runs tsc across all packages to ensure type safety. |
pnpm desktop:build:mac | Builds the macOS universal (Apple Silicon + Intel) installer. |
pnpm desktop:build:win | Builds the Windows NSIS installer (should be run on Windows). |
pnpm db:reset | Resets the local JSON database. |
Sources: CONTRIBUTING.md:20-24, package.json:18-24, apps/desktop/electron-builder.yml:32-35
Build and Release Process
Maintainers release the software by creating git tags. The CI system automatically handles the versioning based on the tag.
- Tagging: Releases are driven by tags (e.g.,
git tag v0.1.8). - CI Workflow: The CI typechecks the code, builds signed/notarized macOS and Windows installers, and publishes them as GitHub Release artifacts.
- Signing: macOS signing requires specific repo secrets (
MAC_CSC_LINK,APPLE_ID, etc.) to produce Gatekeeper-clean.dmgfiles.
Sources: RELEASING.md:5-10, apps/desktop/README.md:46-52
Nudge prioritizes a "finished" feel with restrained AI interaction, focusing on small, well-timed prompts that preserve student ownership of the learning process.
Sources: services/agent/src/prompt.ts:8-13