Skip to main content
Thank you for considering contributing to Freestyle. Contributors mean a lot to us — it’s people like you that grow our community and make this project so fun to work on.

Join our Discord

This is where contributors communicate. All project discussions happen here. If you have any questions, Discord is the place to ask.

​
Prerequisites

  • Node.js 22+
  • pnpm 10+

​
Setup

1

Fork and clone

2

Install dependencies

3

Start development

This starts the Electron app with hot-reloading via electron-vite. The embedded Hono server starts automatically on a local port.On first launch, macOS will prompt for:
  1. Microphone access
  2. Accessibility access (required for paste simulation and global key listener)

​
Project structure

​
Build

​
Development workflow

  1. Create a branch from main
  2. Make your changes
  3. Run pnpm biome check . to verify lint and formatting
  4. Run pnpm --filter @freestyle-voice/electron typecheck:web to verify types
  5. Commit — husky runs Biome on staged files automatically
  6. Open a PR against main

​
Code style

  • Biome for linting and formatting (not ESLint/Prettier)
  • 2-space indentation, 80-char line width
  • Imports are auto-sorted by Biome

​
Commit messages

Follow conventional commits:

​
Freestyle Cloud backend

Only needed if you’re working on the Freestyle Cloud transcription provider. Most contributors can skip this section.
The Freestyle Cloud backend is a separate Cloudflare Worker that exposes the /v1/transcribe endpoint. The desktop app calls it when “Freestyle Cloud” is the selected voice model.
  1. In the cloud repo’s apps/server, create local secrets from the template:
  2. Start the Worker with Wrangler (defaults to http://localhost:8787):
  3. Point the desktop app at it by adding this to apps/electron/.env.local, then restart pnpm dev:
.dev.vars is gitignored — never commit real keys.