Contributing - OpenWhispr

We welcome contributions. Here’s how to get started.

Setup

git clone https://github.com/OpenWhispr/openwhispr.git
cd openwhispr
npm install
npm run dev

Use Node.js 24 (pinned in .nvmrc). Running npm install with a different major version produces an incompatible lockfile.

Development scripts

Command	Description
`npm run dev`	Start with hot reload
`npm start`	Production mode
`npm run build:renderer`	Build the React app
`npm run pack`	Build unsigned app for testing
`npm run lint`	Run ESLint
`npm run format`	Format with Prettier
`npm run compile:native`	Compile native helpers (Globe key, paste binaries)
`npm run download:whisper-cpp`	Download whisper.cpp for current platform

Architecture

The app has two windows sharing one React codebase:

Main window — minimal overlay for dictation controls
Control panel — full settings, history, notes, and integrations

Key layers:

Main process (main.js) — Electron main, IPC handlers, database
Preload (preload.js) — secure bridge between main and renderer
Renderer — React 19, TypeScript, Tailwind CSS v4, shadcn/ui

Tech stack

React 19, TypeScript, Tailwind CSS v4, Vite
Electron 41 with context isolation
better-sqlite3 with FTS5
shadcn/ui with Radix primitives
whisper.cpp + sherpa-onnx for local transcription

Submitting changes

Fork the repo
Create a feature branch (git checkout -b feature/my-feature)
Run npm run lint before committing
Open a pull request

Guidelines

Use TypeScript for new React components
Follow existing patterns in src/helpers/ and src/hooks/
All new UI strings must use the i18n system (9 languages supported)
Test on your target platform before submitting
Add translation keys to all language files in src/locales/

FAQFrequently asked questions about OpenWhispr.