voxtype Install Guide

voxtype is a standalone PyPI package for fully on-device voice dictation on macOS. It types transcribed speech into whatever app has focus. No cloud, no accounts, no audio leaving the machine.

Install

One command; it picks the best engine for the machine automatically (Apple-GPU parakeet-mlx on Apple Silicon, CPU parakeet elsewhere):

uv tool install voxtype

If the user doesn't have uv, either install it first (curl -LsSf https://astral.sh/uv/install.sh | sh) or use pipx install voxtype.

Note: voxtype only works on macOS (it types via macOS accessibility APIs). Tell the user this up front if they are on Linux/Windows.

Configure

Run the interactive wizard — it asks a handful of explained questions (engine, activation mode, hotkey, ...) and writes ~/.config/voxtype/config.toml:

voxtype setup

This must run in the user's own terminal (it is interactive); do not run it through an agent shell. Alternative for hand-editors: voxtype init writes a fully commented sample config instead.

Editing the config directly

All settings live in ~/.config/voxtype/config.toml — every key is optional and the file voxtype init writes is fully commented. You (the agent) can open and edit this file to help the user tune specific options; common ones:

• engine — parakeet-mlx (Apple GPU), parakeet (CPU), or moonshine.
• mode — toggle (hotkey), wake (wake word), or vad (always on).
• segmentation — hold (whole take on toggle-off) or vad (per pause).
• hotkey — toggle chord, e.g. "<ctrl>+;" (run voxtype hotkey to record one).
• sounds — set false to silence the start/stop chimes.
• wake_word / wake_word_aliases, submit_phrases, overlay, paste_hotkey, cancel_hotkey, copy_to_clipboard, and more.

For the full list — every key, its default, and the engine comparison — read the Configuration & CLI reference: https://pchalasani.github.io/claude-code-tools/tools/voxtype/configuration/

Launch

voxtype

Then: press Ctrl+; (default hotkey), speak, press Ctrl+; again — the take is transcribed and typed at the cursor. Esc cancels a recording. Saying "go", "over", or "submit" alone presses Enter.

First-run notes for the user:

• macOS will prompt for Microphone, Accessibility, and Input Monitoring permissions for the terminal app — all three must be granted, then voxtype restarted.
• The first launch downloads the speech model (up to ~2 GB for the default Apple-GPU engine, ~490 MB for the CPU engine); later launches skip the download and just load it onto the GPU (a few seconds, shown by a spinner).

Reference

• Config file: ~/.config/voxtype/config.toml (fully commented; edit to tune any setting)
• voxtype --help — all flags and subcommands
• Config reference (every key + defaults): https://pchalasani.github.io/claude-code-tools/tools/voxtype/configuration/
• Overview & full docs: https://pchalasani.github.io/claude-code-tools/tools/voxtype/