Skip to main content
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 22 (pinned in .nvmrc). Running npm install with a different major version produces an incompatible lockfile.

​
Development scripts

CommandDescription
npm run devStart with hot reload
npm startProduction mode
npm run build:rendererBuild the React app
npm run packBuild unsigned app for testing
npm run lintRun ESLint
npm run formatFormat with Prettier
npm run compile:nativeCompile native helpers (Globe key, paste binaries)
npm run download:whisper-cppDownload 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 39 with context isolation
  • better-sqlite3 with FTS5
  • shadcn/ui with Radix primitives
  • whisper.cpp + sherpa-onnx for local transcription

​
Submitting changes

  1. Fork the repo
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Run npm run lint before committing
  4. 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/