Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides the technical foundation and procedural requirements for contributing to the OpenLive project. OpenLive is designed as a focused, small codebase that emphasizes direct implementation over complex abstractions. It includes a voice-enabled AI tutor system ("Nudge") integrated into a desktop application shell.
The project follows a monorepo structure managed by pnpm, encompassing a Next.js web interface, an Electron desktop shell, agent services for WebSocket communication, and various shared packages for database access and model harnessing.
Sources: CONTRIBUTING.md:1-5, package.json:1-5
Development Environment Setup
To begin contributing, the environment must meet specific version requirements for Node.js and the package manager. The repository uses pnpm to manage its workspace dependencies and enforces a minimum Node.js version.
System Requirements
| Requirement | Minimum Version | Note |
|---|---|---|
| Node.js | 22.13 | Defined in engines |
| pnpm | 11.5.2 | Version pinned in package.json |
Sources: CONTRIBUTING.md:9-11, package.json:7-10
Initial Commands
Once the requirements are met, use the following commands to initialize the project and start the development servers:
pnpm install
pnpm desktop:dev # web + agent servers, opens the desktop window
pnpm dev # web + agent only, open http://localhost:3000
Sources: CONTRIBUTING.md:13-20
Repository Architecture
The project is organized into logical units that separate the UI, the AI agent logic, and shared utilities.
Directory Structure
- apps/desktop: Electron shell responsible for local servers, permissions, windows, and auto-updates.
- apps/web: Next.js UI containing the on-device voice engine (
src/lib/live). - services/agent: Handles the
/liveWebSocket and manages model tools. - packages/harness: Model adapters for providers like Anthropic and OpenAI.
- packages/shared: The wire protocol and shared TypeScript types.
- packages/db: A JSON-file store for keys, settings, and conversations.
Sources: CONTRIBUTING.md:32-39
Development and Build Workflow
The following diagram illustrates the workflow from development to local builds across different platforms.
Sources: CONTRIBUTING.md:13-26, package.json:12-25
Development Guidelines
Contributors are expected to adhere to the project's architectural philosophy and coding standards.
Core Principles
- Direct Code: Favor short, direct code over layers of abstraction.
- Documentation: Use comments to explain the "why" behind specific implementations.
- Small Changes: Pull requests should be focused on one idea at a time.
- Type Safety: The project enforces strict typing;
pnpm typecheckmust pass before pushing changes.
Sources: CONTRIBUTING.md:42-50
Security and Safety (SSRF Protection)
When contributing to tools that interact with the web, such as fetch_url, developers must use provided security guards. For example, the isPrivateIp and hostIsPrivate functions prevent the agent from accessing loopback, private, or cloud metadata addresses.
// Example of SSRF guard implementation in services/agent/src/tools.ts
async function hostIsPrivate(hostname: string): Promise<boolean> {
if (isIP(hostname)) return isPrivateIp(hostname);
if (/^(localhost|.*\.local)$/i.test(hostname)) return true;
try { const { address } = await dnsLookup(hostname); return isPrivateIp(address); }
catch { return true; } // unresolvable → refuse
}
Sources: services/agent/src/tools.ts:49-62
Content Security Policy (CSP)
The web application implements a strict CSP to secure model-authored HTML and on-device AI operations. Developers must update the CSP in apps/web/next.config.ts if adding new model hosts or external assets.
| CSP Directive | Policy | Purpose |
|---|---|---|
default-src | 'self' | Deny by default |
connect-src | 'self' blob: data: ${LIVE_WS} ${MODEL_HOSTS} | Allow WS and HF Hub |
worker-src | 'self' blob: | Required for onnxruntime-web |
script-src | Includes 'wasm-unsafe-eval' | Required for WebAssembly models |
Sources: apps/web/next.config.ts:18-35
Release Process
Releases are managed by maintainers through a tag-driven CI/CD process.
- Tagging: A release is triggered by creating a git tag (e.g.,
v0.1.8). No manual version bump inpackage.jsonis required. - CI Pipeline: CI automatically runs typechecks, builds signed/notarized macOS universal installers and Windows installers, and publishes them to the GitHub release.
- Signing Requirements: macOS signing requires repository secrets including
MAC_CSC_LINK,APPLE_ID, andAPPLE_TEAM_ID.
Sources: RELEASING.md:3-12
Bug Reporting
When reporting bugs, include the following details to facilitate debugging:
- Operating System and App Version (found in Settings or About menu).
- Steps to Reproduce: What you did vs. what happened.
- Logs: Console logs from the application are highly recommended.
Sources: CONTRIBUTING.md:54-56
The contribution process ensures that OpenLive remains a performant, secure, and maintainable platform for AI-assisted learning. By following these guidelines, contributors help preserve the "Nudge" persona—a calm, precise, and context-aware assistant.