Raw capture — raw/handy.md

url: https://github.com/cjpais/Handy date_fetched: 2026-07-05 backfilled: true

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:

Handy isn't trying to be the best speech-to-text app—it's trying to be the most forkable one.

The process is entirely local:

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.

Source · by @mattiacolombomc

Handy is built as a Tauri application combining:

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).

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

handy --toggle-transcription    # Toggle recording on/off
handy --toggle-post-process     # Toggle recording with post-processing on/off
handy --cancel                  # Cancel the current operation

Startup flags:

handy --start-hidden            # Start without showing the main window
handy --no-tray                 # Start without the system tray icon
handy --debug                   # Enable debug mode with verbose logging
handy --help                    # Show all available flags

Flags can be combined for autostart scenarios:

handy --start-hidden --no-tray

macOS tip:When Handy is installed as an app bundle, invoke the binary directly:/Applications/Handy.app/Contents/MacOS/Handy --toggle-transcription

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

Whisper Model Crashes:

Wayland Support (Linux):

Text Input Tools:

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

Display Server Recommended Tool Install Command
X11 xdotool sudo apt install xdotool
Wayland wtype sudo apt install wtype
Both dotool sudo apt install dotool(requiresinputgroup)

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

Other Notes:

-

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.

If you are having trouble with the app, running with the environment variable WEBKIT_DISABLE_DMABUF_RENDERER=1may help

If Handy fails to start reliably on Linux, see Troubleshooting → Linux Startup Crashes or Instability.

Global keyboard shortcuts (Wayland):On Wayland, system-level shortcuts must be configured through your desktop environment or window manager. Use the CLI flags as the command for your custom shortcut.GNOME:- Open Settings > Keyboard > Keyboard Shortcuts > Custom Shortcuts - Click the +button to add a new shortcut - Set the NametoToggle Handy Transcription - Set the Commandtohandy --toggle-transcription - Click Set Shortcutand press your desired key combination (e.g.,Super+O) KDE Plasma:- Open System Settings > Shortcuts > Custom Shortcuts - Click Edit > New > Global Shortcut > Command/URL - Name it Toggle Handy Transcription - In the Triggertab, set your desired key combination - In the Actiontab, set the command tohandy --toggle-transcription Sway / i3:Add to your config file ( ~/.config/sway/configor~/.config/i3/config):bindsym $mod+o exec handy --toggle-transcription Hyprland:Add to your config file ( ~/.config/hypr/hyprland.conf):bind = $mainMod, O, exec, handy --toggle-transcription - Open - You can also manage global shortcuts outside of Handy via Unix signals, which lets Wayland window managers or other hotkey daemons keep ownership of keybindings: Signal Action Example SIGUSR2Toggle transcription pkill -USR2 -n handy``SIGUSR1Toggle transcription with post-processing pkill -USR1 -n handyExample Sway config: bindsym $mod+o exec pkill -USR2 -n handy bindsym $mod+p exec pkill -USR1 -n handy pkillhere simply delivers the signal—it does not terminate the process.

Overlay & Pasting Issues (Linux):

The following are recommendations for running Handy on your own machine. If you don't meet the system requirements, the performance of the application may be degraded. We are working on improving the performance across all kinds of computers and hardware.

For Whisper Models:

For Parakeet V3 Model:

We're actively working on several features and improvements. Contributions and feedback are welcome!

Debug Logging:

macOS Keyboard Improvements:

Opt-in Analytics:

Settings Refactoring:

Tauri Commands Cleanup:

Handy release artifacts are signed with Tauri's updater signature format. The public key is stored in src-tauri/tauri.conf.json under plugins.updater.pubkey.

To verify a release manually, set ARTIFACT to the filename you downloaded, save the pubkey value from src-tauri/tauri.conf.json to handy.pub.b64, then decode the public key and matching .sig file from base64 and verify the artifact with minisign:

# Replace with the file you downloaded
ARTIFACT="Handy_0.8.1_amd64.AppImage"
python3 - "$ARTIFACT" <<'PY'
import base64, pathlib, sys
artifact = sys.argv[1]
pub = pathlib.Path("handy.pub.b64").read_text().strip()
pathlib.Path("handy.pub").write_bytes(base64.b64decode(pub))
sig = pathlib.Path(f"{artifact}.sig").read_text().strip()
pathlib.Path(f"{artifact}.minisig").write_bytes(base64.b64decode(sig))
PY
minisign -Vm "$ARTIFACT" \
  -p handy.pub \
  -x "$ARTIFACT.minisig"

On success, minisign prints:

Signature and comment signature verified

Do not use gpg for these .sig files.

If you're behind a proxy, firewall, or in a restricted network environment where Handy cannot download models automatically, you can manually download and install them. The URLs are publicly accessible from any browser.

The typical paths are:

Inside your app data directory, create a models folder if it doesn't already exist:

# macOS/Linux
mkdir -p ~/Library/Application\ Support/com.pais.handy/models
# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:APPDATA\com.pais.handy\models"

Download the models you want from below

Whisper Models (single .bin files):

Parakeet Models (compressed archives):

For Whisper Models (.bin files):

Simply place the .bin file directly into the models directory:

{app_data_dir}/models/
├── ggml-small.bin
├── whisper-medium-q4_1.bin
├── ggml-large-v3-turbo.bin
└── ggml-large-v3-q5_0.bin

For Parakeet Models (.tar.gz archives):

Final structure should look like:

{app_data_dir}/models/
├── parakeet-tdt-0.6b-v2-int8/     (directory with model files inside)
│   ├── (model files)
│   └── (config files)
└── parakeet-tdt-0.6b-v3-int8/     (directory with model files inside)
    ├── (model files)
    └── (config files)

Important Notes:

Handy can auto-discover custom Whisper GGML models placed in the models directory. This is useful for users who want to use fine-tuned or community models not included in the default model list.

How to use:

Important:

If Handy fails to start reliably on Linux — for example, it crashes shortly after launch, never shows its window, or reports a Wayland protocol error — try the steps below in order.

1. Install (or reinstall) gtk-layer-shell

Handy uses gtk-layer-shell for its recording overlay and links against it at runtime. A missing or broken installation is the most common cause of startup failures and can manifest as a crash or a hang well before any window is shown. Make sure the runtime package is installed for your distro:

Distro Package to install Example command
Ubuntu/Debian libgtk-layer-shell0 sudo apt install libgtk-layer-shell0
Fedora/RHEL gtk-layer-shell sudo dnf install gtk-layer-shell
Arch Linux gtk-layer-shell sudo pacman -S gtk-layer-shell

If it is already installed and you still see startup problems, try reinstalling it (e.g. sudo pacman -S gtk-layer-shell again) in case the library files were corrupted by a partial upgrade.

2. Disable the GTK layer shell overlay ( HANDY_NO_GTK_LAYER_SHELL)

If installing the library does not help, you can skip gtk-layer-shell initialization entirely as a workaround. On some compositors (notably KDE Plasma under Wayland) it has been reported to interact poorly with the recording overlay. With this variable set, the overlay falls back to a regular always-on-top window:

HANDY_NO_GTK_LAYER_SHELL=1 handy3. Disable WebKit DMA-BUF renderer ( WEBKIT_DISABLE_DMABUF_RENDERER)

On some GPU/driver combinations the WebKitGTK DMA-BUF renderer can cause the window to fail to render or to crash. Try:

WEBKIT_DISABLE_DMABUF_RENDERER=1 handyMaking a workaround permanent

Once you've found a flag that helps, export it from your shell profile (~/.bashrc, ~/.zshenv, …) or from the desktop autostart entry that launches Handy. If you launch Handy from a .desktop file, you can prefix the Exec= line, e.g.:

Exec=env HANDY_NO_GTK_LAYER_SHELL=1 handyIf a workaround helps you, please open an issue describing your distro, desktop environment, and session type — that information helps us narrow down the underlying bug.

The goal is to create both a useful tool and a foundation for others to build upon—a well-patterned, simple codebase that serves the community.

MIT License - see LICENSE file for details.

Handy is open-source software, but the Handy name, logo, icon, and brand assets are not open-source. Unofficial forks, rewrites, and redistributions must use their own branding and must not imply endorsement or affiliation.