Skip to content

About

Voice-first productivity for macOS: dictation, meeting notes, live Obsidian context, and optional Beeper/Hermes workflows.

Topics

Resources

Stars

15 stars

Watchers

0 watching

Forks

Repository files navigation

WonderWhisper app icon

WonderWhisper

Dictate anywhere. Capture every meeting. Keep the context you need within reach.

An open-source, voice-first productivity app for macOS.

Latest release macOS 15.5 or newer on Apple Silicon MIT license

WonderWhisper — voice-first productivity 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.

One app, three useful layers

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.

Meeting notes

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 companion during a call: live transcript, Obsidian context cards, and the minimized recording pill

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.

Walkthrough: your first meeting

  1. Open Settings → Meetings. Pick a transcription engine (Parakeet needs no key) and, if you use Obsidian, choose your vault root and export folder.
  2. 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.
  3. 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.
  4. Collapse the companion to the recording pill when you need the screen back.
  5. 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.

Obsidian context and export

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 and Command Mode

Dictation is the fastest path from speech to text:

  1. Focus a text field in any Mac app.
  2. Hold the Dictation hotkey and speak.
  3. 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 AI models

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.

Vocabulary

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.

Where things live

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.

iCloud settings sync

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.

Privacy model

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.

Install

WonderWhisper requires macOS 15.5 or newer on Apple Silicon.

Homebrew

brew install --cask dkapo88/tap/wonderwhisper

Manual download

  1. Download the latest signed and notarized DMG from GitHub Releases.
  2. Drag WonderWhisper.app into Applications.
  3. Open Settings → Permissions and grant the capabilities you use:
    • Microphone
    • Screen & System Audio Recording
    • Accessibility
    • Input Monitoring
  4. Choose a transcription engine in Settings → Transcription. Parakeet is the no-key, on-device default.
  5. Add API keys only for optional cloud providers or integrations.

Either way, grant the permissions in step 3 on first launch.

Updates

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.

Upgrading from HermesWhisper

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.

Optional integrations

Codex

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.

Beeper

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.

Hermes Agent

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).

Build from source

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.xcodeproj

Build from the command line:

xcodebuild \
  -project WonderWhisper.xcodeproj \
  -scheme WonderWhisper \
  -configuration Debug \
  -skipPackagePluginValidation \
  build

Run the test suite:

xcodebuild \
  -project WonderWhisper.xcodeproj \
  -scheme WonderWhisper \
  -destination 'platform=macOS' \
  -skipPackagePluginValidation \
  test

The project uses Swift Testing with @Test and #expect.

Project layout

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.

Troubleshooting

  • 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.app copy.

Contributing

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.

License

WonderWhisper is available under the MIT License.

Model credits

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.

About

Voice-first productivity for macOS: dictation, meeting notes, live Obsidian context, and optional Beeper/Hermes workflows.

Topics

Resources

Stars

15 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages