GitHub - cjpais/Handy: A free, open source, and extensible speech-to-text application that works completely offline

A free, open source, and extensible speech-to-text application that works completely offline.

Handy is a cross-platform desktop application that provides simple, privacy-focused speech transcription. Press a shortcut, speak, and have your words appear in any text field. This happens on your own computer without sending any information to the cloud.

Handy was created to fill the gap for a truly open source, extensible speech-to-text tool. As stated on handy.computer:

For detailed build instructions including platform-specific requirements, see BUILD.md.

Control Handy from Raycast — start/stop recording, browse transcript history, manage dictionary, switch models and languages.

Handy includes an advanced debug mode for development and troubleshooting. Access it by pressing:

Handy supports command-line flags for controlling a running instance and customizing startup behavior. These work on all platforms (macOS, Windows, Linux). Largely this is a beta feature.

Remote control flags (sent to an already-running instance via the single-instance plugin):

Flags can be combined for autostart scenarios:

macOS tip: When Handy is installed as an app bundle, invoke the binary directly:

Advanced users on macOS and Linux can rewrite text right before Handy pastes it. Put an executable at hooks/transcription in Handy's app data folder (~/Library/Application Support/com.pais.handy/ on macOS, ~/.local/share/com.pais.handy/ on Linux). Handy writes the text to its stdin, after any LLM post-processing, and pastes its stdout. One trailing newline is removed, and empty output pastes nothing. If the hook fails or runs longer than 30 seconds, the original text is pasted.

The hook doesn't get your shell's PATH: on macOS, Handy started from the Dock or Finder only sees /usr/bin:/bin:/usr/sbin:/sbin. Use absolute paths for anything else, such as /opt/homebrew/bin/opencc.

Example that prefixes # when Terminal is the frontmost app (macOS):

This project is actively being developed and has some known issues. We believe in transparency about the current state:

Using a Bluetooth headset microphone on macOS may temporarily reduce playback quality or volume while recording because Bluetooth switches to bidirectional audio. Keep your headphones as the output device and select your Mac's built-in or an external microphone in Handy to avoid this.

Shortcuts that include the fn (Globe) key only work on Apple keyboards — your Mac's built-in keyboard or an Apple external keyboard. They will never trigger on a third-party keyboard, even while it is connected to the same Mac.

This is a hardware limitation rather than a Handy bug. fn is not part of the standard USB HID keyboard specification: Apple reports it through a vendor-specific usage that macOS honors only from Apple devices, while third-party keyboards handle their Fn key entirely in firmware and send nothing to the computer. There is no event for Handy to listen for.

If you switch between a MacBook keyboard and an external one, pick a shortcut built from standard modifiers (ctrl, option, shift, command) or a regular key instead.

For reliable text input on Linux, install the appropriate tool for your display server:

Without these tools, Handy falls back to enigo which may have limited compatibility, especially on Wayland.

Runtime library dependency (libgtk-layer-shell.so.0):

Handy links gtk-layer-shell on Linux. If startup fails with error while loading shared libraries: libgtk-layer-shell.so.0, install the runtime package for your distro:

For building from source on Ubuntu/Debian, you may also need libgtk-layer-shell-dev.

The recording overlay is disabled by default on Linux (Overlay Position: None) because certain compositors treat it as the active window. When the overlay is visible it can steal focus, which prevents Handy from pasting back into the application that triggered transcription. If you enable the overlay anyway, be aware that clipboard-based pasting might fail or end up in the wrong window.

Handy picks the WebKit renderer on Linux from the linked WebKitGTK version: 2.54 and newer keep the compositor on shared memory (WEBKIT_DMABUF_RENDERER_FORCE_SHM=1), older releases disable DMA-BUF rendering (WEBKIT_DISABLE_DMABUF_RENDERER=1). Explicit values for either variable are preserved. For rendering workarounds, see Troubleshooting → Configure the WebKit renderer.