LocalFlow

LocalFlow is a native macOS 26+ menu-bar dictation utility. Audio transcription (WhisperKit) and text refinement (MLX) execute on-device after the one-time model downloads. Refined text is copied to the clipboard so you can paste it wherever you need it.

Features

• Refined mode conservatively fixes grammar, punctuation, filler words, and stutters with a local Llama model.
• Verbatim mode skips the LLM and copies the Whisper transcript immediately.
• A configurable global shortcut or menu command starts and stops recording.
• A floating recording overlay shows microphone activity, elapsed time, and processing status.
• Processing can be cancelled and has a configurable timeout. If refinement fails or times out, LocalFlow copies the raw transcript.
• Searchable local history lets you review, copy, and delete earlier dictations.
• History can be disabled, limited by retention period, or configured to retain usage metadata without transcript text.
• The selected refinement model and its memory keep-alive setting persist between launches.
• Launch at login uses macOS's native Login Items service and reports when approval is required.
• The Storage tab shows, downloads, and removes the Whisper and Llama models individually.

Models

LocalFlow downloads its models from Hugging Face the first time each stage runs:

Stage	Model	Purpose
Transcription	argmaxinc/whisperkit-coreml — large-v3-v20240930_626MB	Converts recorded speech to text with WhisperKit.
Refinement (default)	mlx-community/Llama-3.2-1B-Instruct-4bit	Cleans up the transcript using the faster, smaller MLX model.
Refinement (optional)	mlx-community/Llama-3.2-3B-Instruct-4bit	Cleans up the transcript using the larger, more accurate MLX model.

You can select either refinement model in LocalFlow's settings. All inference remains on the Mac after the model files have been downloaded.

WhisperKit stores its model under ~/Library/Application Support/LocalFlow/WhisperKit. MLX uses the standard Hugging Face hub cache (normally ~/.cache/huggingface/hub for this non-sandboxed app). Storage controls remove only the model repositories LocalFlow uses, leaving unrelated Hugging Face downloads intact.

Open and run

Open Package.swift in Xcode 26 or later, let Swift Package Manager resolve its dependencies, select LocalFlow, and Run. The first dictation downloads the Whisper model; the first refinement downloads the selected MLX model. macOS will request microphone access when needed.

For normal use, build and launch LocalFlow as a macOS application bundle instead of using swift run:

The command-line build requires full Xcode 26 or later and its Metal Toolchain to compile MLX shaders. The standalone Command Line Tools are insufficient. After installing Xcode in /Applications, select it and complete its first-launch setup:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
xcrun --sdk macosx metal --version

If the last command reports that the Metal compiler is unavailable, install the component and verify again:

xcodebuild -downloadComponent MetalToolchain
xcrun --sdk macosx metal --version

Adjust the Xcode path if installed elsewhere. If you have set DEVELOPER_DIR, update or unset it because it overrides xcode-select. An unable to spawn process 'metal' error means this compiler is unavailable; the subsequent missing .dia diagnostics warnings are consequences of that failure.

Then build and launch:

./Scripts/build-app.sh
open .build/apps/release/LocalFlow.app

The script uses xcodebuild to compile both the executable and MLX's Metal shaders, with build products under .build/xcode. It verifies that mlx-swift_Cmlx.bundle/Contents/Resources/default.metallib exists, copies dependency resource bundles into the app, and also installs the shader library beside the executable as Contents/MacOS/mlx.metallib, an explicit MLX lookup location. Pass debug to build a debug app under .build/apps/debug.

If refinement reports “Failed to load the default metallib”, the running executable cannot locate its compiled MLX shaders. Native swift build can produce an executable without those shaders. Quit any running LocalFlow instance, rebuild with this script, and launch the resulting .app using the command above. The successful compilation of individual runtime shaders does not establish that the required default library is present. To debug the packaged app in Xcode, launch it and use Debug → Attach to Process → LocalFlow.

The application appears as LocalFlow in the menu bar. Its Audio settings list all Core Audio input devices and remember the selected microphone. The Shortcut settings let you record a custom key combination for starting and ending dictation; the default is ⌘⌥R. Choose Verbatim or Refined mode from the menu or Model settings. The General tab can register the app to launch at login; install the finished app in /Applications first so macOS registers a stable bundle path. Set CODE_SIGN_IDENTITY when invoking the build script if you have an Apple Development or Developer ID certificate; otherwise the script applies an ad-hoc signature suitable for local testing.

When history logging is enabled, completed dictations are stored as JSON Lines records in ~/Library/Logs/LocalFlow/localflow.log. The History settings control transcript retention and can preserve only timestamp, mode, duration, and word-count metadata. The History window provides a searchable interface for retained entries.

The project targets Swift 6 with actor-isolated speech and LLM services. Its only runtime dependencies are the requested Apple-Silicon-local WhisperKit and MLX packages.