Harp is a background daemon for Linux (Wayland) that turns your voice into text, typed live into the focused window. Harp is local-first and real-time: while you hold (or, in toggle mode, after you click) Ctrl+Space, audio is re-decoded over a rolling window with faster-whisper, and the stable prefix is typed as you speak — with minimal backspace+retype back-patches when the model revises an earlier word. There is no cloud LLM step and no separate command mode: one hotkey, one mode, fully on-device.

For in-depth information, please refer to our documentation:

• CLI Reference: Full guide to the harp command and its options.
• Deployment & Setup: Detailed guide on permissions, dependencies, and configuration.
• Internal Architecture: How Harp works under the hood.
• Development Guide: How to contribute and run tests.

...

• Local-First, Fully Offline: Powered by faster-whisper. Your voice never leaves your machine.
• Real-Time Streaming Dictation: While you speak, Harp re-decodes a rolling window and types the stable prefix live, using LocalAgreement-2 to commit only words confirmed across consecutive passes.
• Back-Patch Typing: When the model revises an earlier word, Harp emits a minimal backspace + retype diff instead of waiting until the end — your buffer always reflects the current best transcription.
• Single Hotkey, Single Mode (Ctrl + Space): Hold to dictate, or --toggle to click-on / click-off. No separate command mode; no clipboard-context mode.
• Direct Keyboard Emulation: Transcribed text is typed directly into the focused application via uinput.
• Model Management CLI: Easily download, list, and manage Whisper models (tiny, base, small, medium, large-v3) via harp models.
• Tunable Cadence (--slide): Control how often the rolling window is re-decoded — match it to your hardware's decode wall-time for stable streaming.
• Modern CLI: Terminal UI powered by Rich.

The fastest way to run Harp without manual environment setup:

uvx harpio

For a persistent global installation:

pipx install harpio

git clone https://github.com/apiad/harp.git
cd harp
uv sync
uv run harp start

1. Permissions: Harp requires access to /dev/input and /dev/uinput.

sudo usermod -aG input $USER
# You may also need to set udev rules for uinput or run:
sudo chmod 666 /dev/uinput

2. Whisper Model: Before starting for the first time, download a Whisper model.

harp models download base

3. Dependencies: Ensure libportaudio2 and wl-clipboard (for Wayland clipboard support) are installed.

sudo apt install libportaudio2 wl-clipboard

Start the daemon using the CLI. By default, running harp without arguments starts the background daemon in "Hold Mode" and only prints the result to the terminal.

harp

• harp: Starts the background daemon (alias for harp start).
• harp start: Starts the background daemon with explicit options.

You can customize Harp's behavior using the following flags:

Live dictation, all symbols, toggle:

harp start --toggle --full --type

Slow CPU with a larger model: raise the slide so re-decodes don't queue.

harp start --type --slide 1.5

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

This repository is enhanced with custom Gemini CLI commands to automate common tasks and workflows. If you are using Gemini, you can run:

gemini /onboard

to get started, explore the project architecture, and understand the automated workflows (planning, debugging, releases, etc.).

1. Report Bugs: Open an issue if you find something broken.
2. Suggest Features: Have an idea for a new mode? Let us know!
3. Submit Pull Requests:
   • Fork the project.
   • Create your Feature Branch (git checkout -b feature/AmazingFeature).
   • Commit your changes (git commit -m 'feat: Add some AmazingFeature').
   • Push to the branch (git push origin feature/AmazingFeature).
   • Open a Pull Request.

Distributed under the MIT License. See LICENSE for more information.