Dictate anywhere. Capture every meeting. Keep the context you need within reach.
An open-source, voice-first productivity app for macOS.
WonderWhisper brings dictation, meeting intelligence, and voice-driven workflows into one native Mac app. Its local-first path works without sending audio to a cloud service, while optional providers add faster streaming, post-processing, live context, and integrations when you want them.
| Dictate | Meet | Connect |
|---|---|---|
| Speak into any focused text field with a global hotkey. Clean up the result, preserve your voice, or transform selected text with Command Mode. | Record microphone and Mac system audio, follow a live transcript, take manual notes, surface Obsidian context, and export a Markdown summary. | Create and reply to Codex tasks by voice, send messages through Beeper, or run long-lived tasks against a Hermes Agent server. |
Hermes is now an optional integration—not the identity of the app. WonderWhisper is designed as a broader voice workspace that remains useful even when Codex, Hermes, and Beeper are never configured.
WonderWhisper can start a meeting manually or automatically when it confirms a Google Meet, Slack Huddle, or another configured calling app. During the meeting it keeps separate microphone and system-audio tracks, so headphones and output volume do not determine whether remote speakers are captured.
The meeting workflow includes:
- Durable microphone and system-audio capture in bounded local segments.
- Automatic detection with editable trigger apps and conservative start/stop confirmation.
- Free on-device transcription with Parakeet Unified by default.
- Optional Soniox V5 live transcription, including an echo-reduced mixed-stream beta and a source-separated fallback.
- A floating companion with Transcript, Context, and Notes tabs. Drag it by its header.
- A compact recording pill when minimized, showing elapsed time and live audio level. Click to reopen, drag to move.
- Manual notes that save continuously and are included in the final meeting summary.
- Optional generated summaries, decisions, and action items through OpenRouter.
- Local Obsidian search with links and bounded excerpts for live context.
- Markdown export to a chosen folder inside your Obsidian vault.
- Webhook export: finished notes are POSTed as JSON (full Markdown, title, time, duration, note id) to the endpoints you add in Settings → Meetings → Webhooks, with optional HMAC signing, Keychain-stored custom headers, retries and a delivery log.
- Open Settings → Meetings. Pick a transcription engine (Parakeet needs no key) and, if you use Obsidian, choose your vault root and export folder.
- Join a call. If automatic detection is on, WonderWhisper confirms the call and shows a "Recording meeting" toast with Keep and Discard. Otherwise press Start meeting in the Meetings tab.
- The companion opens beside your call. Transcript follows both sides of the conversation, Context surfaces related notes from your vault, and Notes takes your own bullet points.
- Collapse the companion to the recording pill when you need the screen back.
- Press Stop. The meeting appears in the Meetings library with your notes, an optional generated summary, and an Export button that writes Markdown into your vault.
Stopping a meeting ends capture immediately. Final transcript tokens, recovery, generated notes, and export continue safely in the background.
Meeting settings use two paths for different jobs:
- Vault root is searched locally for notes related to the live conversation.
- Export folder is where WonderWhisper writes finished meeting Markdown files; it can be any nested folder inside the vault.
Vault ranking happens on your Mac. If live AI context is enabled, only a bounded recent transcript window and bounded excerpts from the best local matches are sent to the selected OpenRouter model.
Dictation is the fastest path from speech to text:
- Focus a text field in any Mac app.
- Hold the Dictation hotkey and speak.
- Release to transcribe, optionally clean up, and insert the result.
Command Mode treats speech as an instruction instead. It can work with selected text, a recently copied value, the focused text field, local screen OCR, and your custom vocabulary.
Typical commands include:
- “Make this shorter and warmer.”
- “Turn this into a launch checklist.”
- “Reply politely and ask for a timeline.”
- “Explain the selected paragraph in plain English.”
Fresh installs default Dictation to Fn/Globe and Command Mode to Right Option. Both shortcuts are configurable.
Transcription and language-model processing are separate choices.
| Engine | Where it runs | Best for |
|---|---|---|
| Parakeet: Bark Clean / Unified / Ultra | On device | Private, free transcription. Bark Clean (English) is the dictation default for new installs and removes ums, false starts and repeated words as you speak; Unified (English, punctuated) runs meetings and remains available for dictation; Ultra adds multilingual coverage. Bark Clean and Unified boost words from your Vocabulary list. |
| Qwen3-ASR 0.6B | On device | Offline file transcription after you stop recording. Multilingual MLX model; first use downloads about 1 GB. The model verifies itself on load, and dictation falls back to Parakeet or Groq if it misbehaves. Not used for meetings. |
| Groq Whisper Large V3 Turbo | Cloud | Fast batch transcription through Groq. |
| Soniox V5 | Cloud | Low-latency streaming dictation and optional live meeting transcription. |
| OpenRouter Voice | Cloud | Choosing supported speech-to-text models through OpenRouter. |
| xAI Grok Speech-to-Text | Cloud | xAI batch or streaming transcription. |
OpenRouter powers optional dictation cleanup, Command Mode, meeting summaries, and live context. Models are selected from your favourites in Settings. Reasoning can be omitted, disabled, or enabled at a small level; Omit offers the broadest compatibility, while Off should only be used with models that accept reasoning-free requests.
API credentials are stored in macOS Keychain. You only need keys for the providers and integrations you enable.
Add names, jargon, and product terms under Vocabulary in the sidebar. Parakeet Bark Clean and Unified use the list to rescore recognition on device, including in meetings, and Groq, Soniox, and OpenRouter cleanup receive it as spelling hints. Toggle on-device boosting in Settings → Transcription.
The main window holds the things you work in, grouped in the sidebar:
| Group | Surfaces |
|---|---|
| Library | History, Meetings |
| Modes | Dictation, Command |
| Agents | Hermes chat |
| Tools | Vocabulary, Compare |
Everything you configure lives in the native Settings window (Cmd+, or the menu bar icon), with tabs for General, Transcription, Models, Audio, Meetings, Shortcuts, Integrations, and Permissions.
Turn on Settings → General → Sync settings with iCloud to share vocabulary, prompts, model choices, and preferences across your Macs. It is off by default. API keys, permissions, and device-specific settings such as microphones and hotkeys stay on each Mac.
WonderWhisper makes the local/cloud boundary explicit:
| Data or operation | Default behaviour | Sent elsewhere only when… |
|---|---|---|
| Microphone and system audio | Captured and segmented locally | A cloud transcription engine is selected. |
| Parakeet or Qwen transcription | Audio processing runs locally; audio never leaves your Mac | Resulting transcript text is included only when you enable OpenRouter cleanup, generated notes, or live context. |
| Manual notes and meeting history | Saved locally | Generated meeting notes are explicitly enabled. |
| Obsidian search and ranking | Runs locally in the chosen vault | Live AI context is enabled; only bounded matching excerpts are included. |
| Dictation text | Can remain local with Parakeet or Qwen and no cleanup | OpenRouter cleanup or a cloud STT engine is enabled. |
| Beeper or Hermes content | Unused by default | You configure and invoke the relevant integration. |
Local application data is stored under ~/Library/Application Support/HermesWhisper/. The legacy internal directory name is intentionally retained so existing users keep their meetings, history, settings, and credentials after upgrading to WonderWhisper.
WonderWhisper requires macOS 15.5 or newer on Apple Silicon.
brew install --cask dkapo88/tap/wonderwhisper- Download the latest signed and notarized DMG from GitHub Releases.
- Drag WonderWhisper.app into Applications.
- Open Settings → Permissions and grant the capabilities you use:
- Microphone
- Screen & System Audio Recording
- Accessibility
- Input Monitoring
- Choose a transcription engine in Settings → Transcription. Parakeet is the no-key, on-device default.
- Add API keys only for optional cloud providers or integrations.
Either way, grant the permissions in step 3 on first launch.
WonderWhisper checks for updates once a day and can install them itself, so you only need to download the app once. You can also check on demand from the WonderWhisper app menu, the menu bar icon, or Settings → Updates. Updates are verified against the developer signature before installing, so macOS permissions carry over rather than needing to be granted again.
Quit HermesWhisper before installing WonderWhisper. The new app deliberately retains the existing bundle identity and storage locations, so macOS permissions, UserDefaults, Keychain credentials, history, and meeting data continue to work.
Because the application filename changed, remove the old /Applications/HermesWhisper.app after installing WonderWhisper to avoid keeping two launchable copies.
The Codex integration (Settings → Integrations → Codex) uses the local Codex App Server bundled with the desktop app; no separate API key is
required. A dedicated hotkey creates a task in a prompt-named folder under today's
~/Documents/Codex/YYYY-MM-DD/ directory, or replies to the frontmost Codex response window.
Replies use Codex Desktop's local task bridge so both sides of the follow-up remain visible in the
same desktop task. WonderWhisper can also pin new tasks, include recent clipboard text, and monitor
projectless tasks created from either app for completed responses.
WonderWhisper can send transcribed voice messages into configured Beeper chats and monitor replies through Beeper Desktop's local API. Beeper Desktop must be running with its Desktop API enabled. Chat IDs, labels, shortcuts, and response polling are configured in Settings → Integrations → Beeper.
The Hermes tab connects to an OpenAI-compatible Hermes Agent /v1 server. It supports parallel sessions, voice or typed replies, persistent local conversation history, and independent response windows. Configure the server URL, bearer token, conversation prefix, and optional agent profile under Settings → Integrations → Hermes. Plain http:// URLs work for servers on your local network or Tailscale (for example http://100.x.x.x:8642/v1).
Requirements:
- Xcode with the macOS 15.5 SDK or newer
- An Apple Silicon Mac running macOS 15.5 or newer
git clone https://github.com/dkapo88/WonderWhisper-macOS.git
cd WonderWhisper-macOS
open WonderWhisper.xcodeprojBuild from the command line:
xcodebuild \
-project WonderWhisper.xcodeproj \
-scheme WonderWhisper \
-configuration Debug \
-skipPackagePluginValidation \
buildRun the test suite:
xcodebuild \
-project WonderWhisper.xcodeproj \
-scheme WonderWhisper \
-destination 'platform=macOS' \
-skipPackagePluginValidation \
testThe project uses Swift Testing with @Test and #expect.
WonderWhisper/ App sources, views, services, providers, and assets
WonderWhisperTests/ Unit and integration tests
Scripts/ Local build, run, and release helpers
docs/assets/ README artwork and product screenshots
Core orchestration lives in DictationViewModel and MeetingCoordinator. Transcription engines share a provider protocol, while OpenRouter is the concrete LLM path. History, meetings, notes, and conversations use local file-backed stores.
- A hotkey does nothing: verify Accessibility and Input Monitoring permissions, then check the shortcut is not claimed by another app.
- The meeting companion will not move: drag it by the header bar with the title and timer. The minimized pill drags from anywhere.
- A meeting has microphone text but no system audio: grant Screen & System Audio Recording permission and restart WonderWhisper.
- Automatic detection is delayed: supported browser calls require both calling-page evidence and microphone activity; automatic starts are intentionally conservative.
- A local model is not ready: the first Parakeet run may need time to prepare model assets.
- A cloud request fails with a reasoning error: set reasoning to Omit or a level the selected model supports.
- Two menu-bar icons appear after upgrading: quit and delete the old
HermesWhisper.appcopy.
Issues and focused pull requests are welcome. Please keep changes scoped, include tests for provider or audio logic where practical, and confirm the macOS build and test suite pass before opening a PR. Never commit API keys or local credentials.
WonderWhisper is available under the MIT License.
The Bark Clean dictation model is built on NVIDIA Parakeet TDT 0.6B v3, post-trained by Conway Research as Underdog Bark 3.0 Clean, and converted to Core ML by FluidInference. It is used under CC BY 4.0 and downloaded from Hugging Face on first use; WonderWhisper does not redistribute it. On-device speech recognition runs through FluidAudio.
