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 runs as a macOS LaunchAgent under the service label com.localvoiceai.localvoice, making it fully independent of any terminal window, IDE, or shell session. Once loaded, the agent is managed through launchctl — either directly or via the convenience make targets that ship with the project. This page covers every service operation you’ll need.

​
Command Reference

The following make targets wrap the underlying launchctl calls and handle path substitution in the plist automatically.
CommandWhat it doesRe-grant permissions?
make installFirst-time build + installYes (once)
make startStart listeningNo
make stopStop listeningNo
make reloadReload plist config (no binary change)No
make updateRebuild + reinstall binaryYes
make uninstallRemove binary + LaunchAgent—
make statusShow launchctl service statusNo
make buildCompile binary only (output: ./localvoice)No
make cleanRemove the compiled ./localvoice binaryNo
make build and make clean operate on the local build artifact only and do not affect the installed service or LaunchAgent. Use make build when you want to compile without installing, and make clean to remove the resulting ./localvoice binary from the project directory.
After make update the binary is recompiled and code-signed with a new hash. macOS treats the new binary as a different executable and revokes both Accessibility and Input Monitoring permissions. You must re-add ~/.local/bin/localvoice to both lists in System Settings → Privacy & Security before the service will work again.

​
Direct launchctl Commands

If you installed LocalVoiceAI from a release tarball (using install.sh) rather than building from source, you won’t have the Makefile available. Use launchctl directly: 
# Start the service
launchctl start com.localvoiceai.localvoice

# Stop the service
launchctl stop com.localvoiceai.localvoice

# Check whether the service is loaded and running
launchctl list | grep com.localvoiceai.localvoice
The launchctl list output shows the PID (if running), the last exit code, and the service label. A PID of - means the service is loaded but not currently running.

​
Checking Logs

All output from localvoice — including recording events, transcription results, and errors — is written to a single log file. This is configured via the StandardErrorPath key in the LaunchAgent plist (~/Library/LaunchAgents/com.localvoiceai.localvoice.plist): 
tail -f /tmp/localvoice.log
Run tail -f /tmp/localvoice.log in a separate terminal while using the service to see real-time feedback: [REC] lines when recording starts, [OK] lines when text is pasted, and [ERROR] lines for anything that goes wrong.
A healthy session looks like this in the log: 
[OK]  Listening... (Accessibility + Input Monitoring permissions required)
[REC] Recording at 48000Hz... (release F10 to stop)
[REC] Captured 3.2s — transcribing...
[OK]  Pasted: open the pull request and assign it to me

​
Auto-Start on Login

The LaunchAgent plist ships with RunAtLoad set to false: 
<key>RunAtLoad</key>
<false/>
This means the service does not start automatically when you log in. To start it, run: 
make start
# or, without make:
launchctl start com.localvoiceai.localvoice
If you want LocalVoiceAI to start automatically every time you log in, open ~/Library/LaunchAgents/com.localvoiceai.localvoice.plist in a text editor, change <false/> to <true/> under the RunAtLoad key, and reload the agent: 
make reload
make reload unloads the current plist, writes the updated version, and reloads it — no binary change, so no permission re-grant is needed.

​
Uninstalling

1

Remove the binary and LaunchAgent

Run make uninstall. This unloads the LaunchAgent from launchctl, deletes the plist from ~/Library/LaunchAgents/, and removes the binary at ~/.local/bin/localvoice.
make uninstall
2

Remove the cached Whisper model (optional)

The ggml-small.bin model (~244 MB) is stored in ~/.cache/localvoice/. If you no longer need it, delete the directory:
rm -rf ~/.cache/localvoice/
3

Remove permissions from System Settings

Open System Settings → Privacy & Security and remove ~/.local/bin/localvoice from both Accessibility and Input Monitoring. macOS will not clean these entries up automatically after the binary is deleted.

Build docs developers (and LLMs) love

Get started for freeTalk to us