Uttrflow

🎙️ Dictation: talk like you'd explain it, and it lands like you wrote it

Hold ⌃ ⌥ (Control and Option) in any app and talk. Let go, and the words land at your cursor.

• Recognition runs on your Mac.
• Clean-up removes fillers, adds punctuation and applies your dictionary, matched by sound.
• Works offline once you have signed in.

In the code: UttrflowAudio → UttrflowSpeech → UttrflowAI → UttrflowPipeline → UttrflowInput, with the dock in Sources/Uttrflow/Dock. Read Docs/pipeline.md and Docs/cleanup.md.

📋 Smart clipboard (Beta): everything you copied, one shortcut away

⇧⌘V opens it · ↑↓ choose · ⌘1 All · ⌘2–⌘9 choose a collection · ⏎ paste · ⌘⏎ paste as plain text · ⌘Z undo a delete · esc close

• It knows code (with a language chip), links, colours, images and paths.
• It re-indents or formats code, and shows you the diff first.
• Secrets are masked. Clips can be pinned, aliased and filed into folders.

In the code: UttrflowClipboard and Sources/Uttrflow/Panel. Read Docs/panel.md and Docs/clipboard-secrets.md.

⇥ AI suggestions (Beta): Any tool, get suggestions as you type

Built for the places with no autocomplete, like a shell on a server or a SQL editor. Grey ghost text finishes the line you're on.

• Tab accepts. In a terminal it is →, because Tab is the shell's own completion, and in an editor ⌥Tab. Keep typing to ignore it; esc hides it.
• Candidates come from your history in that field, then from what is on the Mac, then from a local model.
• It reads the text in and around the field you are typing in, and remembers the lines you send, in SQLite. None of it leaves this Mac. It is off until you switch it on, and you choose the apps.

In the code: UttrflowPredict, UttrflowPredictStore, UttrflowPredictCapture and Sources/Uttrflow/Suggestion. Read Docs/predict.md.

Install

Apple Silicon Mac, macOS 26 or later.

brew install --cask uttrflow/tap/uttrflow

Or download Uttrflow.dmg and drag it to Applications. Either way the app updates itself from then on. uttrflow.com/download names the current version and its size.

The build is not yet notarised by Apple, so the first launch is refused with "Uttrflow is damaged and can't be opened". It is not damaged; macOS says that about any download it has not seen a signature for. Clear the quarantine flag once and it opens:

xattr -dr com.apple.quarantine /Applications/Uttrflow.app

Homebrew quarantines what it downloads too, so the command is needed after either install.

Find your way around

I want to work on…	Start in	Read first
Dictation accuracy or speed	Sources/UttrflowSpeech, Sources/UttrflowAI	Docs/cleanup.md, Docs/measuring-accuracy.md
The dock button	Sources/Uttrflow/Dock	Docs/app-dock.md
The clipboard panel	Sources/UttrflowClipboard, Sources/Uttrflow/Panel	Docs/panel.md
AI suggestions	Sources/UttrflowPredict, Sources/Uttrflow/Suggestion	Docs/predict.md, Docs/predict-accept.md
Typing into other apps	Sources/UttrflowInput	Docs/insertion.md

🤝 Build it with us

Every merged pull request puts you on the wall below. You need no account, API key or server of ours, so a clone builds and runs complete.

• Pick up a good first issue: small, self-contained, and checked to be real before it is filed.
• Ask a question or share an idea in Discussions.
• Read CONTRIBUTING.md for how a change gets in.

git clone https://github.com/uttrflow/uttrflow-swift.git && cd uttrflow-swift
make verify     # lint, audits, build, tests, coverage floor
make app        # builds and signs dist/Uttrflow.app for this Mac

Thank you to everyone who has sent a fix, filed an issue or asked a good question.

Using it, in detail

• ⇧⌘V opens the clipboard over whatever you are typing in. Type to filter, or type an alias you gave a clip. ↑↓ to choose, ⌘1 for All, ⌘2–⌘9 to choose a collection, ⏎ to paste where the caret already was, ⌘⏎ to paste as plain text however it was copied, ⌘Z to undo a delete, Esc to close. The window underneath never loses focus.
• Hold ⌃⌥ and talk. Let go, and the words land at the cursor in the app you were already in. The floating button at the screen edge shows the microphone level while you hold it, and the shortcut can be changed in Settings.
• Dictionary. A name the recogniser keeps getting wrong is fixed once; matching is by sound, so spellings you have not seen yet are caught too.
• Tab-to-complete, once you turn it on in Settings → AI suggestions. The rest of the line appears in grey ahead of the caret as you type; Tab takes it, typing on ignores it, and ⌥↓ opens the alternatives when there is more than one. Tab is already spoken for in a terminal and in an editor, so those take a completion with → and ⌥Tab instead, and the key can be set per application.

The first dictation asks for the microphone, and typing into another app needs Accessibility — which tab-to-complete needs three times over: to read the field, to watch the keyboard, and to write the completion. The clipboard needs neither to open.

The clipboard records text, links, code, colours, images and file paths, and works out which is which rather than asking. Code gets a language chip, can be re-indented, and can be run through a formatter you already have installed — the diff is shown first, and the result is compared token for token with what went in and discarded if it differs. Clips can be pinned, filed into folders (⌘2 upwards), renamed and deleted. Anything that looks like a secret is masked at a fixed width that does not reveal its length, and gets no tooltip.

Dictation is push-to-talk and on-device. Recognition runs through WhisperKit or Apple's speech recogniser, then a clean-up stage turns what was said into what was meant: fillers go, punctuation arrives, and the words in your dictionary are spelled your way. Each engine declines what it cannot handle, so a language Apple's model does not cover is routed to one that does.

Tab-to-complete is off until you turn it on, and then it finishes the line you are typing in another application. A completion comes from what this Mac has entered in that same field before, or from what is on the machine right now — a branch name, a program on PATH — or, when neither has anything, from a line the local model writes. Turning it on fetches about 3 GB of model weights; the remembered and machine-known completions do not wait for them. It stays quiet more often than it speaks: a password field, a selection, a caret that is not at the end of its line, a field that reports no caret to draw at, or three completions typed past in one field are each reason enough to draw nothing. Four editors ship switched off, because their own completion already reads the whole file. Docs/predict.md is the full account.

Works offline. Signing in needs a network exactly once. After that every launch, every dictation and every paste works with Wi-Fi off — proven by a sandbox that fails any test touching the network.

A clone runs without anything of ours

Worth saying early, because it is the question every reader of a client repository has: you do not need an API key or access to any server we run.

Dictation is on-device. The clipboard, history, dictionary and snippets live in Application Support and are never sent anywhere. The released app asks you to sign in before anything else opens; a development build signs in against an in-process stand-in, so its sign-in needs no network and no account of ours. An account carries the things that genuinely need one: a dictionary between Macs. Uttrflow is free and open source: there are no subscriptions, paid plans or billing.

So a clone builds, tests and runs, complete. See CONTRIBUTING.md.

Building it

Apple Silicon Mac, macOS 26 or later. Xcode 26.6 or later supplies the toolchain; the build itself is SwiftPM.

make verify     # lint, PII audit, build, test suite, coverage floor, offline audit
make app        # builds and ad-hoc signs dist/Uttrflow.app
open dist/Uttrflow.app
make help       # every target

Optionally, to make the sign-in buttons look like the shipping app:

./Scripts/fetch-provider-marks.sh

That fetches Google's mark from Google. It is not in this repository — it is their trademark, not ours — and nothing needs it: without it the button carries its wording alone, exactly as the GitHub button does in every build.

make app signs ad-hoc, which is enough to run here and to keep the permission grants across rebuilds, but Gatekeeper will refuse the bundle on a Mac that did not build it. To put a build on another Mac, or to release one, see Docs/releasing.md. Docs/packaging.md explains why the app is built with xcodebuild rather than swift build.

Under the hood

All the deciding lives in Swift Package Manager modules; the app target holds windows, menu items and SwiftUI views, and no judgement at all. That split is deliberate: it means swift test exercises the entire product headlessly, with no simulator, no UI runner and no Xcode scheme.

Sources/
  UttrflowCore         Shared protocols, models, errors and utilities; imports Foundation, Darwin and os.
  UttrflowAudio        Microphone capture, resampling, WAV encoding, file reading.
  UttrflowSpeech       Speech to text. One engine, two interchangeable recognisers.
  UttrflowAI           Turning a transcript into the words the speaker meant.
  UttrflowContext      What is on screen, so terms and names can be got right.
  UttrflowInput        Getting finished text into whatever the user is typing in.
  UttrflowPipeline     The sequence: listen, transcribe, tidy, insert. And cancelling it.
  UttrflowSettings     What the user chose, kept between launches.
  UttrflowHistory      What was dictated, kept between launches and aged out on a clock.
  UttrflowDictionary   Words you say that a general model does not know, found by sound.
  UttrflowDiagnostics  Opt-in crash and hang reports. The only module that links the crash reporter.
  UttrflowAccount      Who is signed in, and whether the account is still valid.
  UttrflowClipboard    Clipboard history, classification and storage; panel UI lives in Uttrflow/Panel.
  UttrflowPredict      Finishing a line you have typed before: the turn, the gates, the ranking.
  UttrflowPredictStore The corpus of what you have typed, on this Mac, in SQLite.
  UttrflowPredictCapture
                       What may be learned from, and where, and what is refused outright.
  UttrflowUX           What every window and menu should say, decided without drawing it.
  UttrflowPermissions  Reading and requesting what macOS gates the pipeline behind.
  UttrflowEval         Scoring how well it hears and how well it tidies. No model near it.
  UttrflowLocalModel   An open-weight model on the GPU, for languages Apple's misses.
  UttrflowTestSupport  Fakes and fixtures shared by every test target. Never shipped.
  Uttrflow             The app. Windows and wiring only.
  uttrflow-dev         Developer harness. One command per stage of the pipeline.
  uttrflow-eval        Word error rate and latency, against passages read aloud.
                      Never linked into the app: it can reach the private corpus.
  uttrflow-bakeoff     Scores every clean-up engine against the corpus.

Each capability is defined once, as a protocol in UttrflowCore, and implemented in its own module. Nothing above the protocol layer — not the pipeline, not a view — refers to a concrete engine. Docs/ has a page per subsystem, from insertion and its traps to how accuracy is measured.

swift run uttrflow-dev doctor                 # permissions and audio hardware
swift run uttrflow-dev models install         # one-time, 646 MB
swift run uttrflow-dev record -s 5            # record 5s, write a WAV
swift run uttrflow-dev transcribe -s 6        # record and transcribe
swift run uttrflow-dev transcribe voice.wav   # transcribe a file
swift run uttrflow-dev clean "um so i think the the deployment is uh still running"
swift run uttrflow-dev insert "Hello from Uttrflow."   # needs Accessibility access

record asks for microphone access the first time. Run from a terminal, the permission belongs to the terminal app rather than to Uttrflow — real first-run behaviour can only be checked once the app bundle exists.

Which implementations run is decided entirely by EngineConfiguration:

EngineConfiguration(
    speech: .whisperKit,
    transformerPreference: [.foundationModels, .localModel, .rules]
)

Clean-up engines are tried in order, and the first one that reports itself able to handle the request wins. An engine that cannot cope with the spoken language steps aside rather than producing bad output — which is how Hindi is routed away from Apple's model, whose 23 supported locales do not include it. The preference list must always end in .rules, which can handle anything, so the pipeline can never dead-end.

make verify builds, tests and gates the whole product with swift build — that is the everyday path, and the pre-push hook needs nothing else.

Two things go through xcodebuild instead. The app, because of the resource-bundle problem described in Docs/packaging.md. And UttrflowLocalModel with uttrflow-bakeoff, because they link MLX, whose Metal shaders SwiftPM's command line cannot compile:

xcodebuild -downloadComponent MetalToolchain   # once, ~690 MB, only for the bake-off
make bakeoff                                   # scores every clean-up engine

MLX is quarantined in that one module and that one executable on purpose, so the everyday tools, the tests, the pre-push gate — and make app — never need the Metal toolchain.

Quality bar

• 95% line coverage per module, enforced by Scripts/coverage.sh and the pre-push gate
• Swift 6 language mode, strict concurrency, warnings as errors
• No force unwraps, no force try, no implicitly unwrapped optionals (lint-enforced)
• A PII audit runs first in make verify, so no real name, address or credential can be committed by accident

Privacy

Dictation happens entirely on your Mac. Audio is kept on this Mac for a day, and only so a failed dictation can be retried: every recording is written beside the buffer the recogniser reads and deleted the moment the words land. If the words are lost — the recogniser fails, or the app dies mid-dictation — the recording stays for a day and sits at the top of the Dictation page with a Retry. The recording is encrypted in authenticated chunks with a device-only Keychain key; nothing about it leaves the Mac. See Docs/recordings.md. The text is kept locally so you can copy or re-insert it, and deleted after its retention window. Your dictionary, your history and your settings are files on this Mac; signing out does not remove them, and only Reset does.

When you are signed in and Clipboard is enabled, Uttrflow records copies it can keep in ~/Library/Application Support/Uttrflow — encrypted JSON indexes and encrypted copied picture files beside them. Files use a device-only key held in Keychain; the clipboard panel decrypts its in-memory copy as needed. Clips age out after the retention window (seven days by default, five hundred clips) unless you pin them. None of it leaves this Mac: there is no clipboard sync.

• Password managers' concealed mark is honoured. Concealed text is treated as a secret and is not written to clipboard history or saved clips. See Docs/clipboard-secrets.md for what the marker and secret handling cover.
• Clipboard capture can be excluded per app or paused for an hour. Settings keeps a private list of excluded apps and offers a one-hour pause. Exclusions use the declared clipboard writer when available, with the frontmost app as a fallback. Remote clipboard copies are attributed to another device. No apps are excluded by default. These controls do not replace the concealed marker or secret detection. See Docs/clipboard-secrets.md.

Clips that look like secrets are masked in the panel until you ask to see them, at a fixed width that does not reveal how long the token is, and they get no tooltip. Secret text can appear in the running panel, but is not written to clipboard history or saved clips. See Docs/clipboard-secrets.md.

Tab-to-complete reads the text in and around the field you are typing in, such as the thread above a reply box, and hands it to a model that runs on this Mac. None of it is uploaded.

Tab-to-complete learns from what you type, and that corpus is the most sensitive thing the app keeps. It is predict.v1.sqlite in the same Application Support folder, sealed with the device's local Keychain key and protected by owner-only file permissions; it is never uploaded. Nothing is written until you have been asked: the first time you finish a value in an application Uttrflow asks once whether it may learn there, keeps the answer in predict-consent.v1.json, and records nothing in the meantime — so the choice is per application, and an application you said no to stays refused silently. A field that hides what is typed into it is refused before anything else is considered, because a password field a completion has seen is a password in a database; so are values shaped like a credential, values that would destroy data if they were ever completed and run, and anything shorter than two characters (CaptureGate in Sources/UttrflowPredictCapture). A field keeps at most 2,000 entries. You can forget one line, everything one application taught, or all of it.

There is an account, and nothing opens until you sign in. Signing in needs a network exactly once; every launch after that works without one, and an entitlement that has aged out still lets you dictate rather than locking you out. Signing out, or a session the server has ended, closes every window and stops dictation until you sign in again.

Usage statistics are off by default. When enabled, they are sent linked to your account while signed in; they can only carry numbers, and one switch turns them off. Once an hour, and when the app quits, Uttrflow sends a report of counts and timings: how many dictations started, were cancelled or failed, total recording and waiting time, how many characters were inserted, latency percentiles, language mix, which stage failed, and the app and macOS versions. It is not that we choose not to send your words: the type that gets encoded has no field capable of holding text at any depth, and a test walks it and fails on anything String-shaped. Audio, transcripts, dictionary contents, window titles and application names have nowhere to go. Settings → Privacy → "Share usage statistics" turns it on, and turning it off drops anything not yet sent. Docs/account-telemetry.md has the detail.

Crash reports are off unless you turn them on. Settings → Privacy → Send crash reports is the one exception to the paragraph above, and it starts off. When it is on, a crash or a freeze is reported to Sentry, the error tracker the project uses: the app and macOS versions, the Mac model and architecture, the exception, and the stack as binary names and addresses. No user or host name, no file paths (each is cut to its file name), no breadcrumbs, and nothing you dictated or copied. Builds made from source carry no reporting key and never send anything. Docs/crash-reporting.md has the details.

The app is not hermetic and does not claim to be: it downloads a speech model on first run, roughly 646 MB, and signs you in once. After that it dictates with no network at all. No clean-up engine is hosted, and the evaluation corpus is not a library product so it cannot be imported into the app.

Contributing

• CONTRIBUTING.md — how a change gets in, and what review looks for
• RELEASING.md — how a release is cut, and why there is no staging branch
• SECURITY.md — reporting a vulnerability, and what runs automatically
• CHANGELOG.md — what changed, per version
• uttrflow.com — the site, and what the app is for

Licence

MIT — see LICENSE. The code is yours to fork, modify and ship, commercially included.

The name and the mark are not covered by it, and MIT has no trademark clause of its own, so TRADEMARK.md says the one thing this asks of a fork: give it your own name and your own icon. Somebody who cannot tell a fork from the original cannot make an informed decision about what is reading their microphone.

Sign-in provider marks belong to their owners and are not in this repository at all; see Scripts/fetch-provider-marks.sh.