Contributing

Where to start

1. 1

   Read the project README

   The Develop section covers toolchain, debug runs, and the three-window frontend model. You need Node 20.19+ (22 LTS recommended), Rust stable plus MSVC and the VS Build Tools C++ workload.

2. 2

   Pick a lane

   Rust core (global hotkeys, clipboard simulation, keyring, tray) or React frontend (main, overlay, pill). Docs fixes are first-PR friendly.

3. 3

   Reproduce first

   For behavior changes, reproduce on Windows 10/11 with a provider key before writing code.

Source lives at FlunkeyManager/flunkey — full guidance in CONTRIBUTING.md.

Setup

Clone the repo and get a dev window running. No .env needed — API keys are entered in-app and stored in Windows Credential Manager.

git clone https://github.com/FlunkeyManager/flunkey.git
cd flunkey
npm install
powershell -File scripts\fetch-whisper.ps1
npm run tauri dev

The fetch-whisper step runs once: it downloads the official whisper.cpp Windows build (~12 MB) into src-tauri/whisper-bin/. MSIX/Store builds additionally need the Windows SDK (makeappx.exe) — see the repo's Microsoft Store packaging doc for identity setup.

Checks before a PR

Run these before opening a pull request:

npm test
npx tsc --noEmit
npm run build

cargo check --manifest-path src-tauri/Cargo.toml
npm run tauri build

Reporting issues

• Open issues on GitHub Issues — include: OS build, Flunkey version, provider, and the hotkey involved
• Paste problems: name the target app (Electron? terminal? browser?) and whether it was elevated
• Never paste API keys, audio, or private dictated text into an issue
• Security issues stay private — see SECURITY.md, never file them as public issues

Pull requests

1. 1

   Fork and branch

   Fork the repo, branch off main, and keep the change focused. Forks use their own Partner Center identity for MSIX builds.

2. 2

   Prove it

   Run the checks above, reproduce the behavior on Windows, and describe the change up front in the PR.

3. 3

   Mind the rules

   No version bumps in package.json / tauri.conf.json / Cargo.toml. No secrets, keyring dumps, AppData JSON, or binaries from src-tauri/target, dist, or whisper-bin.

• Small, scoped PRs with the behavior change described up front
• Privacy rule is absolute: no new network calls except to user-configured providers, no secrets outside Credential Manager
• Update these docs alongside behavior changes — undocumented features get reverted