Something not working? Start here.

Accessibility permission won't stick

HandsFree needs Accessibility permission to type into other apps. Symptoms: you granted it, but the app still says permission is missing, or the checkbox appears on but doesn't take effect.

1. Open System Settings → Privacy & Security → Accessibility.
2. Find HandsFree in the list. If the toggle is already on, turn it off and then on again — a stale entry from a previous version is the single most common cause.
3. Quit HandsFree completely and relaunch it. macOS only re-reads this permission when the process starts, so it will keep reporting the old state until you restart the app.
4. If HandsFree isn't in the list at all, press +, then choose it from your Applications folder.
5. If there are two HandsFree entries, remove both with −, then relaunch and grant permission once. Duplicates happen when the app has been moved or replaced.

Run HandsFree from /Applications, not from the mounted disk image or your Downloads folder. Permission is tied to the app's location and signature, so running it from a different path looks like a different app to macOS.

Still stuck? Reset the permission, below.

Dictation runs but nothing gets inserted

The indicator appears, you speak, it processes — and no text shows up. Work through these in order:

1. Check the text actually got transcribed. Open History from the menu bar. Your words are written to history before insertion is attempted, so if the text is there, this is purely an insertion problem — and nothing you said was lost.
2. Confirm something is focused. Text goes to the focused text field. Click into a real editable field — a note, a search box — and try again. If nothing has keyboard focus, there is nowhere for the text to go.
3. Re-check Accessibility permission using the steps above. Insertion is exactly the capability that permission grants; a missing grant produces this symptom precisely.
4. Try a different app. Dictate into TextEdit. If TextEdit works and your original app doesn't, that app is refusing programmatic text insertion. Some terminals, remote-desktop clients, virtual machines, secure input fields, and games do this deliberately.
5. Password fields never work, by design. macOS secure input blocks all synthetic keystrokes while one is focused — which is a feature, not a bug.
6. Watch for a clipboard change. When direct insertion fails, HandsFree falls back to pasting. If your text ends up on the clipboard but doesn't paste, the app is blocking the simulated ⌘V; paste it manually to confirm, and use a different field or app for dictation.

If nothing appears in History either, the problem is upstream: check that the microphone is granted in System Settings → Privacy & Security → Microphone, that the right input device is selected in Sound settings, and that the model finished downloading.

The model download is stuck or failed

On first run HandsFree downloads its speech-recognition model — around 1.6 GB. Until that finishes, dictation can't work.

• Give it room. Make sure you have at least 3 GB free, and expect a few minutes on a normal connection.
• It's a one-time cost. Once downloaded, the model is reused forever and dictation works offline. It lives at ~/Library/Application Support/HandsFree/models/.
• If it fails partway, quit HandsFree, open that folder in Finder (Go → Go to Folder… and paste the path), delete any file in it that's obviously smaller than it should be, and relaunch to start the download cleanly.
• On a corporate or filtered network, a proxy or content filter may be interrupting a large binary download. Try a different network — a personal hotspot is a fast way to test.
• VPNs and metered connections often throttle or drop long transfers. Turn them off for the download.

Downloading the model doesn't send us anything about you. It's a public model file — see the privacy policy.

Resetting permissions from scratch

When macOS gets into a confused state about a permission — usually after an app update or a move — the reliable fix is to revoke the grant entirely and re-approve it. This is safe: it deletes no data of yours, only the permission record.

1. Quit HandsFree from the menu bar.
2. Open Terminal and run whichever applies:

   tccutil reset Accessibility com.heypran.handsfree
   tccutil reset Microphone com.heypran.handsfree

3. Relaunch HandsFree. It will ask for the permission again as though newly installed. Approve it, then quit and relaunch once more.

If tccutil reports an error, do it by hand instead: in System Settings → Privacy & Security, select HandsFree under both Accessibility and Microphone and remove it with −, then relaunch the app.

Note that permissions are keyed to an app's bundle identifier and its code signature, so a version with a new signature legitimately needs a fresh grant — that isn't a malfunction.