vtmate can run in the background with no terminal, driven by global shortcuts from any
application: select some text in your browser or editor, hold a shortcut, talk, release it.
Replies are spoken only. It also doubles as a system-wide dictation and read-aloud tool. The
four shortcuts below all have defaults - to change them, or if the daemon reports one as
already taken, see Background Shortcuts.
Starting it, attaching and detaching
vtmate --daemon # start it (models load once, then it waits for shortcuts)
vtmate # attach: the normal terminal view of the daemon conversation
vtmate --daemon-status # is it running? which shortcuts?
vtmate --daemon-stop # stop it
Running plain vtmate attaches to the daemon and gives you
the full normal terminal view: the live transcript, the status bar and the usual keys
(SPACE push-to-talk, ESCAPE,
u, arrows, Ctrl+D,
Ctrl+S, Ctrl+E).
Ctrl+C only detaches - the daemon keeps
running until vtmate --daemon-stop.
vtmate -a <agent_name> while attaching switches straight to that agent
(same effect as arrowing to it - conversation reset included); vtmate -c <agents_file>
reloads the daemon's agents from that file live, picking up edits to the running agent
without resetting the conversation (unless it switches to a different agent because the
previous one no longer exists in the file). Both flags can be combined.
Only one daemon runs at a time. Its files live in ~/.vtmate:
daemon.pid, daemon.sock (Linux/macOS) and daemon.log
(diagnostics only, never the conversation). The daemon always works in push-to-talk mode -
the microphone is only open while a shortcut is held.
Platform notes: on Linux, global shortcuts and reading the selection need
X11 (Wayland has neither - under Wayland, run vtmate in an X11 session; the selection used
is the primary selection, whatever is highlighted, no Ctrl+C needed). On
Windows and macOS, the selection is read by simulating Ctrl+C/Cmd+C
and the clipboard is restored afterward; on macOS the vtmate binary needs the
Accessibility permission (System Settings → Privacy & Security →
Accessibility) to simulate keys.
Talk with an LLM (with or without selected text)
Hold llm_background_ptt_combo (default ctrl+alt+a)
to talk. On release your speech is transcribed and, if some text is selected anywhere on the
desktop, the selection is appended after the speech (speech first, blank line, selection).
The whole thing is sent to the agent as one message and the reply is spoken. Pressing the
combo again while a reply is playing interrupts it. The selection is sent once: what you
selected since your previous message - select it again to send it a second time, and nothing
is appended when nothing is selected.
Resetting the conversation
llm_background_reset (default ctrl+q) works
like ESCAPE in the terminal: press once to stop the speech, twice within a
second to also reset the conversation (history cleared) - which also stops an in-progress
save. A desktop notification "Conversation restarted!" confirms the reset.
Read a selected text aloud (TTS)
tts_background_combo (default ctrl+alt+r)
reads the selected text aloud, no LLM involved, including any code in it. Press it again
while it is speaking to stop. Reading uses the selection up, so it is not appended to your
next LLM message as well.
Speech to text and paste
Hold stt_and_paste_background_ptt_combo (default
ctrl+alt+s) to talk. On release your speech is transcribed
and written at the cursor of the application you're in. On Linux it is typed out, so it
works in terminals too (where Ctrl+V is not the paste shortcut) and your
clipboard is left alone; on Windows and macOS it is pasted through the clipboard, whose
previous contents are put back afterward. No LLM, nothing spoken.
Starting on boot
If you need to start vtmate when your computer boots, check
scripts/vtmate-as-service examples.
Linux - systemd user unit
vtmate.service runs vtmate --daemon-foreground under
systemd --user (so systemd supervises the process directly, with
Restart=on-failure), started on graphical-session.target rather
than plain login so it doesn't crash-loop on a headless SSH session.
cd scripts/vtmate-as-service/linux
./install-systemd.sh
systemctl --user status vtmate # watch it
./uninstall-systemd.sh # remove it
macOS - LaunchAgent
com.vtmate.daemon.plist installs as a per-user LaunchAgent. Needs the
Accessibility permission granted to the vtmate binary (see above).
cd scripts/vtmate-as-service/macos
./install-launchd.sh
launchctl print gui/$(id -u)/com.vtmate.daemon # watch it (logs: ~/Library/Logs/vtmate.log)
./uninstall-launchd.sh # remove it
Windows - Scheduled Task
A per-user Scheduled Task triggered "at log on" - not a Windows Service, since services
have no desktop session either. It resolves vtmate.exe from PATH
first, falling back to the installer's default
%LOCALAPPDATA%\Programs\vtmate\bin\vtmate.exe; pass a custom path as the
script's first argument if you installed elsewhere.
install-vtmate-task.bat
schtasks /query /tn vtmate /v /fo list :: watch it
uninstall-vtmate-task.bat :: remove it