Invoke
Voice-to-prompt for developers.
Hold a button, speak, release. Your words hit the clipboard (or auto-paste at your cursor) in under a second. GPU-accelerated local transcription via Whisper — no cloud round-trip for speech-to-text.
Optionally run your transcription through an AI reformatter to clean it up into structured prompts for Claude Code, Cursor, Windsurf, Copilot, or raw text.
Install
# CLI only (headless, any platform)
pip install getinvoke
# With GUI (system tray + overlay)
pip install getinvoke[gui]
# Or use pipx for isolated install
pipx install getinvoke
Note: The CLI command is
dictate, notinvoke, to avoid conflict with the pyinvoke task runner.
Quick Start
# Check your setup (GPU, mic, settings)
dictate health
# Run the setup wizard
dictate setup
# Start dictating (headless mode)
dictate run
# Start with GUI (requires [gui] extras)
dictate run # auto-detects GUI availability
Default workflow: Hold Mouse5 (forward side button) → speak → release → text on clipboard.
How It Works
YOU SPEAK into your mic
│
▼
┌─────────────────────────────┐
│ WHISPER (runs locally) │
│ Model: distil-large-v3 │
│ GPU (CUDA) or CPU │
│ No internet. No API key. │
│ │
│ Output: raw transcription │
│ "uh so like fix the um │
│ auth middleware thing" │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ AI REFORMATTER (optional) │
│ │
│ Takes raw speech and │
│ reshapes it based on the │
│ selected MODE: │
│ │
│ Claude Code → conversational│
│ Cursor → @file references │
│ Commit → git commit msg │
│ Raw → just clean up speech │
│ none → SKIP (no AI call) │
│ │
│ Backend options: │
│ • openrouter (cloud API) │
│ • claude-cli (local CC) │
│ • ollama (fully local) │
│ • none (skip AI entirely) │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ CLIPBOARD + AUTO-PASTE │
│ "Fix the auth middleware │
│ to validate JWT tokens │
│ before checking roles" │
└─────────────────────────────┘
Platform Support
| Platform | CLI | GUI (tray + overlay) | Installer | GPU |
|---|---|---|---|---|
| Windows | pip install getinvoke |
pip install getinvoke[gui] |
Download .exe | CUDA (NVIDIA) |
| macOS | pip install getinvoke |
pip install "getinvoke[gui]" |
Download .dmg | MLX (Apple Silicon) |
| Linux | pip install getinvoke |
pip install getinvoke[gui] |
pip install getinvoke[gui,wayland] |
CUDA (NVIDIA) |
Comparison
| Feature | Invoke | whisper.cpp CLI | nerd-dictation | macOS Dictation |
|---|---|---|---|---|
| Local Whisper | Yes | Yes | Yes | No |
| AI reformatting | 5 backends | No | No | No |
| Code-aware modes | 8 modes | No | No | No |
| Project context | Auto-detected | No | No | No |
| GPU acceleration | CUDA + MLX | CUDA/Metal | No | — |
| Privacy mode | Yes (fully offline) | Yes | Yes | No |
| Cross-platform | Win/Linux/Mac | Win/Linux/Mac | Linux | Mac only |
| pip installable | Yes | No | No | — |
Requirements
- Python 3.11+
- NVIDIA GPU (CUDA) or Apple Silicon (MLX) recommended — works on CPU but slower
- Windows, Linux, or macOS
CLI Commands
| Command | Description |
|---|---|
dictate run |
Start Invoke (auto-detects GUI vs headless) |
dictate run --headless |
Force headless mode |
dictate run --no-beep |
Start without audio feedback |
dictate health |
Check GPU, model, mic, API keys, config |
dictate devices |
List audio input devices |
dictate modes |
List available target modes |
dictate history |
View dictation history |
dictate setup |
Run setup wizard |
dictate setup --cli |
Force CLI wizard (no GUI) |
dictate config |
View all configuration |
dictate config mode cursor |
Set a config value |
dictate license status |
Check license status |
dictate license activate <key> |
Activate a license |
dictate install |
Create Windows Startup shortcut |
dictate transcribe <file> |
One-shot WAV transcription |
dictate logs |
View log file |
Configuration
Key Settings
| Setting | Default | Options |
|---|---|---|
reformatter_backend |
none |
openrouter, claude-cli, ollama, none |
mode |
claude-code |
claude-code, cursor, windsurf, copilot, raw, commit, pr |
whisper_model |
distil-large-v3 |
Any faster-whisper model |
whisper_device |
auto |
auto, cuda, cpu |
hotkey |
mouse5 |
mouse5, mouse4, ctrl+shift+d, or any key combo |
auto_paste |
false |
true = insta-dump at cursor |
audio_device |
system default | Device index from dictate devices |
beep_enabled |
true |
true / false |
sound_preset |
default |
default, subtle, arcade, minimal, icq, aim, dial-up |
language |
en |
en, auto, or any Whisper language code |
Set values quickly from the terminal:
dictate config mode cursor
dictate config reformatter_backend claude-cli
dictate config auto_paste true
AI Reformatter Backends
| Backend | Where it runs | What you need | Cost |
|---|---|---|---|
openrouter |
Cloud (OpenRouter API) | OPENROUTER_API_KEY |
~$0.001/dictation |
claude-cli |
Local (your Claude Code) | Claude Code installed | Part of your CC plan |
ollama |
Local (your machine) | Ollama running on localhost:11434 | Free, no internet |
none |
Skipped entirely | Nothing | Free — raw Whisper output only |
Target Modes
| Mode | What the AI does with your speech |
|---|---|
claude-code |
Formats as a conversational prompt for Claude Code |
cursor |
Adds @file references, structured for Cursor's chat |
windsurf |
Cascade-style prompt for Windsurf |
copilot |
GitHub Copilot Chat format |
raw |
Cleans up filler/grammar only — no prompt structure |
commit |
Turns your description into a git commit message |
pr |
Turns your description into a PR title + body |
Custom Hotkeys
The settings GUI has a Record... button to capture any key combo. Or set it from the CLI:
dictate config hotkey "ctrl+shift+r"
dictate config hotkey mouse5
Supports modifier combos (ctrl+shift+d, alt+f2), mouse buttons (mouse4, mouse5), and single keys.
Ollama Setup
# Install Ollama (https://ollama.com)
ollama pull llama3.2
# Configure Invoke to use it
dictate config reformatter_backend ollama
dictate config ollama_model llama3.2
# Default URL: http://localhost:11434
Custom Vocabulary
Boost Whisper recognition for domain-specific terms:
dictate config custom_vocab "KeyGrip,OpenRouter,pyproject,FastAPI,pynput"
History
dictate history # Recent entries
dictate history -n 20 # Last 20
dictate history -s "fix" # Search
History retention defaults to 30 days. Change with dictate config history_retention_days 90.
Audio Feedback
- Short high tick — recording started (hotkey pressed)
- Rising chirp — done, text is on clipboard / pasted
- Disable with
dictate run --no-beepordictate config beep_enabled false
Sound Presets
Choose from 7 sound themes:
| Preset | Vibe |
|---|---|
default |
Original Invoke sounds |
subtle |
Softer, lower tones |
arcade |
Retro game-style chirps |
minimal |
Single short ticks |
icq |
Classic ICQ vibes |
aim |
AIM buddy list chirps |
dial-up |
Modem handshake tones |
dictate config sound_preset icq
Preview all sounds in Settings > General > Sound theme > Preview.
Linux Notes
- Audio stream stays open to avoid ALSA/PipeWire latency on every hotkey press
- If using
pip installon modern Debian/Ubuntu, usepipx install getinvokeinstead (PEP 668)
X11
Auto-paste requires xdotool:
sudo apt install xdotool # Debian/Ubuntu
sudo dnf install xdotool # Fedora
Wayland
Wayland requires a few extra steps for full functionality. Run dictate health at any point to check your setup.
Mouse hotkeys (mouse4/mouse5)
pynput can't capture global mouse events on Wayland. Invoke uses evdev instead, reading directly from /dev/input:
# 1. Install the wayland extra
pip install getinvoke[wayland]
# 2. Add yourself to the input group, then reboot
sudo usermod -a -G input $USER
sudo reboot
Keyboard hotkeys (e.g. ctrl+shift+d) work on Wayland without any extra steps.
Clipboard
On Wayland, wl-clipboard is required so text lands on the native Wayland clipboard (not the X11 one):
sudo dnf install wl-clipboard # Fedora
sudo apt install wl-clipboard # Debian/Ubuntu
Auto-paste
Auto-paste works for XWayland apps (Electron apps like Signal, VS Code, Chrome) via xdotool. Install it as above.
For native Wayland apps on KDE or Sway, also install wtype:
sudo dnf install wtype
GNOME limitation: GNOME's compositor doesn't support the virtual keyboard protocol, so auto-paste only works into XWayland apps on GNOME. For terminals (Claude Code, etc.), auto-paste is not possible on Wayland — text is on your clipboard, paste manually with Ctrl+Shift+V.
| App type | Auto-paste works? |
|---|---|
| Electron apps (Signal, VS Code, Chrome) | Yes — via xdotool (XWayland) |
| Native Wayland apps on KDE/Sway | Yes — via wtype |
| Native Wayland apps on GNOME | No — paste manually with Ctrl+V |
| Terminal emulators | No — paste manually with Ctrl+Shift+V |
System Tray (GUI mode)
When installed with pip install getinvoke[gui], Invoke runs in the system tray with:
- State indicator (idle / recording / processing / error)
- Current AI backend + model displayed
- Mode switcher (right-click menu)
- License management
- Settings editor
- Open logs
- Quit
Use dictate-gui to launch without a console window.
Building the Windows Installer
See the installer README for details on building the .exe installer with PyInstaller + Inno Setup.
Development
pip install -e ".[dev,gui]"
ruff check src/ tests/
ruff format src/ tests/
pytest
Architecture
src/getinvoke/
engine.py # Core pipeline engine (FrontendProtocol + InvokeEngine)
app.py # GUI frontend wrapper (GuiFrontend + InvokeApp)
terminal.py # Rich terminal frontend (TerminalFrontend)
cli.py # Click CLI commands
setup_cli.py # Terminal-based setup wizard
clipboard.py # Copy + auto-paste via pynput
config.py # Settings from config.json / env vars / .env
context.py # Project context loader (18 file types + git)
feedback.py # Audio cues (beeps/chirps)
history.py # SQLite dictation history
hotkey.py # Global hotkey listener (mouse/keyboard)
license.py # Lemon Squeezy license validation (7-day trial)
license_gui.py # License activation dialog (tkinter, GUI only)
modes/ # 7 target mode system prompts
overlay.py # Recording/processing overlay (tkinter, GUI only)
recorder.py # Push-to-talk audio capture (sounddevice)
reformatter.py # LLM reformatting (OpenRouter/Claude CLI/Ollama/none)
settings_gui.py # Settings editor (tkinter, GUI only)
transcriber.py # Whisper model loading + transcription
tray.py # System tray icon + menu (pystray, GUI only)
updater.py # Auto-updater (GitHub releases + pip-aware)
window.py # Active window/file detection
wizard.py # First-run setup wizard (tkinter, GUI only)
installer/
invoke.spec # PyInstaller build config
invoke.iss # Inno Setup installer script
build.ps1 # Local build script
License
MIT — see THIRD-PARTY-LICENSES.txt for bundled dependency licenses.
Metadata
Release files for getinvoke 0.10.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| getinvoke-0.10.6.tar.gz | 150.9 kB | With provenance | Details for getinvoke-0.10.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| getinvoke-0.10.6-py3-none-any.whl | Python 3 | none | any | Details for getinvoke-0.10.6-py3-none-any.whl |
Total release size: 294.2 kB
Release files / getinvoke-0.10.6.tar.gz
| Download URL | getinvoke-0.10.6.tar.gz |
|---|---|
| Size | 150.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b8fbf3c4a2e259dd04533f0d6e6dcd28a163142a852c3a5bc02fd6e16c2f3b27
|
|
BLAKE2b-256 checksum How to use checksums |
1f785dd53ec16070cd269519e75cfdebece773cf45fafb0e1aa8924f0bbafb4b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency logRelease files / getinvoke-0.10.6-py3-none-any.whl
| Download URL | getinvoke-0.10.6-py3-none-any.whl |
|---|---|
| Size | 143.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
96938159f5b169f5044f58ad2ca4f44ba0f6f770ef3801d77765594d1ce2cf5f
|
|
BLAKE2b-256 checksum How to use checksums |
ff4b89c8e8205c958b472a997bfff6843edf5791936e59aaaa2d83887867d343
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency logSecurity for getinvoke 0.10.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for getinvoke-0.10.6.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.