Skip to content
Get packs

Guide · Open source

How to use Handy: offline speech-to-text setup and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

Handy is a free, open source desktop app for speech-to-text that runs offline. You press a keyboard shortcut, speak, and your words are typed or pasted into the active text field. This guide walks through installing Handy, choosing a shortcut and model, dictating, and fixing common problems on Windows, macOS and Linux.

Handycjpais/Handy · ★ 37k · MIT

Quick start

  1. 1Download Handy. Get the latest release from the releases page or handy.computer, or use Homebrew or winget on macOS and Windows.
  2. 2Install the app. On Debian or Ubuntu, install the .deb with APT so dependencies are handled automatically.
  3. 3Grant permissions. Launch Handy and allow microphone and accessibility access when prompted.
  4. 4Set your shortcut. Open Settings and choose a keyboard shortcut, using hold-to-talk or toggle mode.
  5. 5Pick a model. Choose a Whisper model or Parakeet V3 in the app based on your hardware.
  6. 6Dictate. Click into a text field, press the shortcut, speak, and release or tap again to stop.

Install Handy on Windows, macOS or Linux

Download the latest release from the Handy releases page on GitHub or from the Handy website at handy.computer.

On macOS you can also install it with Homebrew, and on Windows with winget. Both of these packages are not maintained by the Handy developers.

On Debian or Ubuntu, install the downloaded .deb file with APT so required dependencies are installed automatically. Avoid dpkg -i unless the dependencies are already present.

  • macOS (Homebrew cask): brew install --cask handy
  • Windows (winget): winget install cjpais.Handy
  • Debian/Ubuntu: install the downloaded .deb file
sudo apt install ./Handy_*.deb

Set up permissions and keyboard shortcuts

Launch Handy and grant the system permissions it asks for, such as microphone and accessibility. Then open Settings to configure your preferred keyboard shortcuts.

Handy supports hold-to-talk, where you hold the shortcut to record and release to stop, and toggle mode, where you tap once to start and again to stop. Hold-only and Toggle-only modes are also available.

Choose a transcription model

Handy transcribes locally with one of two model families. Whisper models (Small, Medium, Turbo, Large) use GPU acceleration when it is available. Parakeet V3 is described as CPU-optimized, with automatic language detection.

Silence is filtered out using Voice Activity Detection (VAD) with Silero before transcription.

  • Whisper (Small/Medium/Turbo/Large): uses GPU when available
  • Parakeet V3: CPU-optimized, automatic language detection

Dictate text into any app

Click into the text field where you want your words. Press the shortcut, speak while it is active, then release (hold mode) or tap again (toggle mode). Handy processes your speech with Whisper and pastes the transcribed text into the app you are using.

Because Handy works in any text field, the same workflow applies to email, documents, chat and code editors.

Control Handy from the command line

Handy accepts command-line flags. Remote control flags are sent to an already running instance. Startup flags change how Handy launches. The README describes CLI flags as a beta feature. Flags can be combined, for example for autostart.

  • handy --toggle-transcription: toggle recording on or off
  • handy --toggle-post-process: toggle recording with post-processing on or off
  • handy --cancel: cancel the current operation
  • handy --start-hidden: start without the main window
  • handy --no-tray: start without the system tray icon
  • handy --debug: enable debug mode with verbose logging
  • handy --help: show all flags
handy --start-hidden --no-tray

Fix Linux text input and Wayland issues

For reliable text input on Linux, install a tool that matches your display server. On X11, install xdotool. On Wayland, install wtype (preferred) or dotool. Dotool requires adding your user to the input group, then logging out and back in.

Without these tools Handy falls back to enigo, which may have limited compatibility, especially on Wayland. The README says Wayland support is limited. On Ubuntu 26.04, which uses Wayland by default, the README says wtype does not work and points to ydotool with a systemd setup described in a linked GitHub comment.

  • X11: sudo apt install xdotool
  • Wayland: sudo apt install wtype
  • Both: sudo apt install dotool (requires the input group)
  • If startup fails with libgtk-layer-shell.so.0 errors, install libgtk-layer-shell0 on Ubuntu/Debian or gtk-layer-shell on Fedora/RHEL
sudo usermod -aG input $USER

Know the macOS limitations

Shortcuts that use the fn (Globe) key only work on Apple keyboards, including the built-in keyboard or an Apple external keyboard. They never trigger on third-party keyboards. If you switch keyboards, choose a shortcut made from ctrl, option, shift, command or a regular key.

If you use a Bluetooth headset microphone on macOS, playback quality or volume may drop while recording. Keep headphones as the output and select the built-in or an external microphone in Handy.

What people use it for

  • Dictating emails, documents and chat messages without sending audio to a cloud service
  • Typing by voice as an accessibility aid
  • Controlling recording from scripts or Raycast using the CLI flags and integration
  • Using a free alternative to paid dictation tools

Frequently asked questions

Is Handy free?

Yes. The README describes Handy as free and open source, and the project is released under the MIT licence.

Does Handy work offline?

Yes. The README says transcription runs locally using Whisper or Parakeet V3 models, so audio is not sent to the cloud.

How do I install Handy on Ubuntu?

Download the .deb file and run sudo apt install ./Handy_*.deb. The README recommends APT over dpkg -i because APT installs required dependencies automatically.

Why does Handy not type on Wayland?

The README says Wayland support is limited and needs wtype or dotool for text input. Install one of these tools and, for dotool, add your user to the input group.

Why does my fn key shortcut not work in Handy?

Shortcuts with the fn (Globe) key only work on Apple keyboards. Third-party keyboards do not send that key to the computer, so use standard modifiers or a regular key instead.

What are the alternatives to Handy?

The README lists comparable projects including Whisper.cpp, Vibe, Buzz and OpenWhispr. Pick based on whether you need a desktop dictation app or a more general transcription tool.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Handy suits people who want private, offline dictation with a free, open source app and a simple hold-to-talk or toggle shortcut. It is a weaker fit for Wayland Linux users who cannot install extra text input tools, Mac users who need the fn key on third-party keyboards, or anyone who needs a fully polished, stable product.

Install options & downloads