Quickstart

Requirements

You need:

Apple Silicon
Microphone permission
Accessibility permission
Network access during setup for packages and model downloads

Install

Recommended installer:

curl -fsSL https://gabrimatic.github.io/local-whisper/install.sh | bash

Manual Homebrew setup:

brew install gabrimatic/local-whisper/local-whisper
wh setup

Source setup for development:

git clone https://github.com/gabrimatic/local-whisper.git
cd local-whisper
./setup.sh

The Homebrew path installs Local Whisper, downloads and warms the default Parakeet-TDT v3 model, checks macOS permissions, and starts the background service. Source setup is for development and unreleased changes. Other MLX speech models download from Settings when selected; the Transcription panel shows progress, partial cache state, and cancel. See Installation for permissions, updates, and uninstall details.

Service controls

Local Whisper runs as one background service. If you close it, update it, or it stops responding, use:

wh status    # Check whether Local Whisper is running
wh start     # Start it again
wh stop      # Stop it
wh restart   # Stop and start cleanly
wh log       # Open the live service log
wh doctor    # Check install, permissions, models, and service health
wh update    # Update Local Whisper, prepare models, rebuild the menu app, and restart

Only one service can run at a time. Homebrew and source installs share the same service lock, so another Terminal or install path cannot start a second running service.

Start dictating

Action	Key
Start recording and copy result	Double-tap Right Option
Hold to record and paste result	Hold Right Option past the double-tap threshold, then release
Stop double-tap recording	Tap Right Option or Space
Cancel	Esc
Read selected text aloud	Option+T
Stop speech	Option+T again or Esc

Double-tap recordings go to the clipboard by default. Hold-to-record recordings paste at the active cursor while preserving the previous clipboard contents. When ui.auto_paste is enabled, all dictation recordings paste at the active cursor.

Check the service

wh status
wh doctor
wh log

Use wh doctor --fix only when you want Local Whisper to repair install, permission, or service issues automatically.

Next steps

Configure engines and backends in Configuration.
Learn the menu bar and overlay in macOS app.
Set up mobile in Mobile apps.

Start

Product

Reference

Requirements

Install

Service controls

Start dictating

Check the service

Next steps

​Requirements

​Install

​Service controls

​Start dictating

​Check the service

​Next steps

Requirements

Install

Service controls

Start dictating

Check the service

Next steps