Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/npateriya/LocalVoiceAI/llms.txt

Use this file to discover all available pages before exploring further.

LocalVoiceAI needs two macOS privacy permissions to function: one to watch for the push-to-talk keypress anywhere on the system, and one to simulate the paste action that delivers transcribed text into whatever app you are using. Both permissions are granted once in System Settings and persist across reboots — you will not be prompted again unless the binary changes.

​
Accessibility

What it does: Accessibility access allows LocalVoiceAI to simulate a Cmd+V keypress (CGEventPost) into the currently focused window. Without this permission, transcribed text cannot be pasted anywhere. How to grant it:
  1. Open System Settings → Privacy & Security → Accessibility.
  2. Click the + button.
  3. Navigate to ~/.local/bin/ and select localvoice.
  4. Confirm the toggle next to localvoice is blue (enabled).

​
Input Monitoring

What it does: Input Monitoring allows LocalVoiceAI to install a CGEventTap at the session level, which detects the Fn+F10 keypress globally — regardless of which app has focus. Without this permission, the service starts but never receives key events. How to grant it:
  1. Open System Settings → Privacy & Security → Input Monitoring.
  2. Click the + button.
  3. Navigate to ~/.local/bin/ and select localvoice.
  4. Confirm the toggle next to localvoice is blue (enabled).
After running make update to rebuild and reinstall the binary, both Accessibility and Input Monitoring permissions must be re-granted. macOS ties authorization to the binary’s cryptographic hash. When the binary changes — even if the path stays the same — the old authorizations are invalidated and LocalVoiceAI will fail to receive key events or paste text until new permissions are added.

​
Verifying Permissions Work

If one or both permissions are missing, the service will fail to create its event tap and exit immediately. Open the log to see the exact error: 
tail -f /tmp/localvoice.log
A missing-permission failure looks like this: 
[ERROR] Event tap failed — missing permissions.
  1. System Settings → Privacy & Security → Accessibility → add localvoice
  2. System Settings → Privacy & Security → Input Monitoring → add localvoice
  Note: re-grant both permissions after every rebuild (binary hash changes)
If you see this message, return to the sections above, remove the existing localvoice entry from both lists (if present), re-add ~/.local/bin/localvoice, ensure both toggles are blue, then restart the service: 
launchctl stop com.localvoiceai.localvoice
launchctl start com.localvoiceai.localvoice
Running localvoice directly from a terminal (e.g., ~/.local/bin/localvoice) may fail with permission errors even after granting access in System Settings. This happens because macOS applies permission checks based on the parent process, and terminal emulators sometimes have conflicting entitlements. Always run LocalVoiceAI through its LaunchAgent — installed via make install and started with make start or launchctl start com.localvoiceai.localvoice — so it runs as its own independent process with the correct authorization context.

Build docs developers (and LLMs) love

Get started for freeTalk to us