🦜 Wordbird
Contextual voice dictation for macOS. Powered by NVIDIA Parakeet running locally on Apple Silicon via MLX.
Press a hotkey, speak, and your words are transcribed and pasted into whatever app is focused. A small LLM post-processes the transcription to fix errors, using project-specific context from a WORDBIRD.md file.
Getting started
Requires macOS on Apple Silicon (M1+) and Python 3.10+.
# Run with uvx (no install needed)
uvx wordbird
# Or run in the background
uvx wordbird start
uvx wordbird stop
uvx wordbird status
Context-aware correction
You can improve transcription with a WORDBIRD.md file which lists project-specific terms that may be misheard.
Either create a standard template, or ask Claude to analyze your project and create the file for you.
uvx wordbird init
# or
uvx wordbird init --claude # uses haiku by default; you can specify model via --claude {haiku,sonnet,opus}
Context detection works with:
- Terminal.app — detects the focused tab's shell working directory
- VS Code / VS Code Insiders — via the Wordbird extension, which works with local and remote (SSH) workspaces
- Zed - detects the focused window's project directory out of the box, no extension needed
Transcription and pasting work in any app.
A WORDBIRD.md file looks like this:
---
transcription_model: mlx-community/parakeet-tdt-0.6b-v2
fix_model: mlx-community/Qwen2.5-1.5B-Instruct-4bit
---
{# Your correction prompt and examples here #}
{# Key terms: MyApp, some_function, PostgreSQL #}
{# Names: Alice, Bob #}
{# Misheard words: "bird word" should be "Birdword" #}
Input: "{{ transcript }}"
Output:
The file is a Jinja template. {{ transcript }} is replaced with the raw transcription. The YAML front matter lets you override models per-project.
Hotkey
| Action | Default |
|---|---|
| Toggle recording | Right ⌘ + Space |
| Transcribe and submit | Right ⌘ + Return (opt-in) |
The submit shortcut transcribes, pastes, and presses Return — useful for chat and terminal workflows. Enable it in the dashboard settings.
Configurable via CLI flags or the dashboard settings:
--modifier-key KEY Modifier key (default: rcmd). Options: rcmd, lcmd, ralt, lalt, rshift, lshift, rctrl, lctrl, fn
--toggle-key KEY Toggle key (default: space). Options: space, return, tab, escape
Options
--model MODEL Transcription model (default: mlx-community/parakeet-tdt-0.6b-v2)
--fix-model MODEL Post-processor model (default: mlx-community/Qwen2.5-1.5B-Instruct-4bit)
--no-fix Disable LLM post-processing
--no-server Don't spawn the API server (run it separately)
Dashboard
Wordbird runs a local web dashboard (default localhost:7870). Click the bird in the menu bar → Dashboard… to open it.
- History — browse transcriptions with timestamps, app name, working directory, and duration. See both original and corrected text.
- Settings — configure hotkey, models, and post-processing. Changes take effect within seconds.
- Stats — words dictated, recording time, WPM, session count.
uvx wordbird history # view history from the CLI
uvx wordbird config # show or create the config file
Data
All data is stored in ~/.wordbird/:
| File | Purpose |
|---|---|
wordbird.toml |
User configuration |
wordbird.db |
Transcription history (SQLite) |
server.json |
Server port discovery |
wordbird.pid |
Singleton lock |
wordbird.log |
Background mode logs |
Menu bar
Wordbird shows a bird icon in the menu bar:
- ⚪ White — idle
- 🟡 Yellow — connecting mic
- 🔴 Red — listening
- ✨ Sparkles — transcribing
Permissions
Wordbird needs three macOS permissions, granted to your terminal app:
- 🎤 Microphone — to record your voice
- 🔐 Accessibility — to paste text
- ⌨️ Input Monitoring — to detect the global hotkey
Wordbird checks these on startup and tells you what's missing.
Architecture
Wordbird runs as two sibling processes managed by a thin CLI:
- Server (
wordbird-server) — FastAPI app handling transcription, post-processing, history, config, and serving the React dashboard - Daemon (
wordbird-daemon) — macOS-native process handling hotkeys, mic recording, overlay HUD, menu bar, and clipboard pasting
The daemon sends recorded audio to the server via HTTP. The server runs ML inference in a thread pool so the dashboard stays responsive during transcription.
uvx wordbird # starts both (recommended)
uvx wordbird-server # just the API server
uvx wordbird-daemon # just the daemon (expects server running)
Development
make backend-dev # API server with hot reload
make daemon-dev # daemon only (expects server running)
make frontend-dev # Vite dev server with API proxy
make dev # backend + frontend + daemon (all three)
make wordbird # build frontend + run everything
make backend-test # run pytest
License
MIT
Metadata
Release files for wordbird 0.10.1
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 |
|---|---|---|---|---|
| wordbird-0.10.1.tar.gz | 713.5 kB | With provenance | Details for wordbird-0.10.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wordbird-0.10.1-py3-none-any.whl | Python 3 | none | any | Details for wordbird-0.10.1-py3-none-any.whl |
Total release size: 974.3 kB
Release files / wordbird-0.10.1.tar.gz
| Download URL | wordbird-0.10.1.tar.gz |
|---|---|
| Size | 713.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
747eeec588431c841e6c1958fb9c7ba7205ef2f107ff4276b9f3ab694cb4c7cd
|
|
BLAKE2b-256 checksum How to use checksums |
89f1a068339a13c0c1c4df20406bf172e9425e9100bcc45cd84049c9a4dfa0e8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Jun 25, 2026.
Transparency logRelease files / wordbird-0.10.1-py3-none-any.whl
| Download URL | wordbird-0.10.1-py3-none-any.whl |
|---|---|
| Size | 260.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
767f28d2c0ce3b4236f3846af560d7036e8773bd9dd1c3069e447adb3e3ae107
|
|
BLAKE2b-256 checksum How to use checksums |
cf038600c01dc634eb2c86c688856101b2c6a658c870514d509944bcbeeaea46
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Jun 25, 2026.
Transparency logSecurity for wordbird 0.10.1
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 wordbird-0.10.1.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 Jun 25, 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.