BetterFingers

A private desktop speech editor. Speak messy thoughts, watch them get refined by a local LLM, review the result, and place clean text into a focused target when the configured platform/backend supports it. Core speech processing runs on your machine: no cloud inference, account, subscription, or telemetry.

A Donaven Crenshaw project · MIT licensed · Windows + Linux Status: public alpha. v1.1.0-alpha.3 includes a signed Windows x64 installer. It is still alpha software; see Project status for the honest boundaries.

---

What it does

Hold a hotkey (or a game-controller button), talk, and BetterFingers:

1. Transcribes your speech locally with Whisper (faster-whisper / CTranslate2).
2. Refines it with a local LLM (Gemma via llama.cpp) through a swappable persona — cleaning up grammar, tone, and formatting instead of dumping raw dictation.
3. Shows you the draft in a review overlay you can edit, re-run, or have read back aloud (Kokoro TTS) before anything lands.
4. Injects final text into the focused target when the configured injection path supports it, and restores your clipboard.
5. Never loses audio — every utterance's raw recording is kept so a failed run is recoverable, not gone.

The whole product is built around one loop: activate → speak → transcribe → refine → review → inject → recover when anything fails.

Why it's different

• Private by design. STT, LLM, and TTS run locally. Network access is used for user-initiated model/runtime downloads and update checks, not cloud inference. A built-in privacy dashboard enumerates data locations and wipes your data on demand.
• Smart, not literal. LLM personas (Formal, Polished, Unhinged, and your own) rewrite what you say. Build new ones with a guided interview (Persona Foundry).
• Cross-app when supported. Hotkeys, selection capture, and injection depend on the desktop/platform path; Wayland is best-effort with honest capability reporting.
• Respects your hardware. The recommender reports model tiers from detected hardware; hardware compatibility remains subject to operator qualification.
• MIT licensed. No account, subscription, or paywall.

Feature highlights

Project status

BetterFingers is a real local-first application with automated tests and a deep feature set. v1.1.0-alpha.3 is a public prerelease with a signed Windows x64 installer. It is not a stable release: hardware/model compatibility, desktop injection paths, and platform-specific selection behavior still need broader outside testing. The release page and its CI-built assets are the public source of truth.

Platforms: Windows is the primary packaged target. Linux can run from source; the source Ctrl+Alt+R selection-rewrite workflow is qualified on X11, while Wayland paths remain compositor-dependent and best-effort. macOS is not supported yet.

Hardware tiers

The in-app recommender detects your tier and never suggests a model that won't fit your RAM. Bigger models are always opt-in.

Privacy model

Speech processing runs on-device. Network access is limited to model/runtime downloads and update checks. No accounts, analytics, or cloud inference. The Privacy dashboard (GET /privacy) lists every data location on disk with sizes and retention, and POST /privacy/wipe verifiably clears drafts, the searchable-history database, and raw recordings. See DESIGN.md §9 for the full data-lifecycle model (a unified DataRegistry and optional at-rest encryption are on the roadmap).

Install

Windows

Download the installer from the v1.1.0-alpha.3 release. The published Windows installer is Authenticode-signed. Windows SmartScreen can still warn on a new, low-reputation alpha; verify the signature and release URL instead of downloading copies from third-party mirrors.

Run from source (Linux)

# Hardware-aware bootstrap: creates ./.venv and installs the torch build that
# matches your machine. On a GPU-less box it installs CPU-only torch, skipping
# the ~3.9 GB of CUDA/nvidia wheels the default install would pull in.
python3 tools/setup_venv.py
cd app && npm install && npm run fix:electron
BETTERFINGERS_PYTHON=../.venv/bin/python npm run dev

The bootstrap auto-detects an NVIDIA GPU via nvidia-smi. Override with --torch cpu or --torch cuda if you want to force a build. The old manual path still works (python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt) but on Linux it always pulls the CUDA stack.

The Electron shell starts the FastAPI backend automatically on port 8000 (BETTERFINGERS_HOST / BETTERFINGERS_PORT are honored end-to-end).

You also need a local llama-server binary for LLM cleanup. BetterFingers looks for it at .betterfingers/llama-server/bin/llama-server; provision one with:

python tools/setup_linux_llama_server.py --from /path/to/llama-server
# or build from a llama.cpp checkout:
python tools/setup_linux_llama_server.py --source .betterfingers/llama.cpp
# CUDA build:
python tools/setup_linux_llama_server.py --source .betterfingers/llama.cpp --cmake-arg=-DGGML_CUDA=ON

Overrides: BETTERFINGERS_LLAMA_SERVER=/path/to/llama-server, BETTERFINGERS_MODEL_PATH=/path/to/model.gguf.

Development

• Tests: python3 -m pytest -q (full suite loads real Whisper/TTS models and peaks around 11 GB RAM — see the OOM note in tests/conftest.py; for fast iteration use python3 -m pytest -q -k "not transcriber and not tts_engine").
• End-to-end: cd app && npx playwright test (needs a local LLM + llama-server on disk for the review-overlay spec; close any running instance first).
• JS syntax check: node --check app/src/renderer/main.js.
• Platform boundaries are documented in SUPPORTED_PLATFORMS.md; Windows release signing lives in WINDOWS_SIGNING.md, and DESIGN.md remains the product/architecture reference.

Architecture

Electron (app/)                      Python sidecar (repo root)
├─ main:    windows, tray,           ├─ server.py    FastAPI (~60 routes) + WebSocket
│           overlays, global         ├─ transcriber  faster-whisper (+ confidence)
│           hotkeys, injection       ├─ llm_engine   llama-server client, personas, chunking
├─ preload: auth + origin bridge     ├─ tts_engine   Kokoro (+ blend / modulation)
└─ renderer: dashboard, overlays     ├─ recorder / hotkey_manager / dictionary / macros
                                     ├─ history_store (FTS5) / recordings / model_manager
   REST + WebSocket boundary  <────> └─ hardware_report / model_recommender / privacy
   (Bearer token, versioned)

Electron owns the desktop surface (windows, tray, overlays, hotkeys, clipboard, injection); Python owns everything model- and data-related (STT, LLM, TTS, personas, recordings, history, privacy). The boundary is an inspectable, version-gated REST + WS API.

Known limitations

• No macOS build.
• The signed Windows installer is still an alpha and may trigger SmartScreen reputation warnings.
• On X11, selection/copy and typing paths require DISPLAY, xclip (or xsel), and xdotool where those paths are used. Wayland best-effort paths use WAYLAND_DISPLAY, wl-copy/wl-paste from wl-clipboard, and wtype or ydotool where the compositor permits them; tool presence alone is not qualification.
• Wayland global hotkeys and text injection are best-effort (OS limitation, not a bug), and Wayland is not qualified on the current host.
• Selected-text TTS, injection/PTT, audio devices, and model performance still vary by desktop, hardware, and target application.
• A local LLM has a real resource footprint on weak hardware — use the tier recommender.
• Voice cloning ships a consent + QA gate but no synthesis engine is bundled yet.

Contributing & security

Found a bug or a security issue? See SECURITY.md for how to report vulnerabilities privately. Roadmap and design rationale: DESIGN.md.

About

BetterFingers is a project by Donaven Crenshaw — private, local-first software that respects you.

License

MIT © 2026 Donaven Crenshaw.