WhisperShortcut

Voice-first AI for your Mac. Press ⌃⌥1 anywhere, speak, and the transcription inserts at the cursor — auto-paste, off by default and direct-download only — or lands on the clipboard, ready to paste into any app. Speak an instruction (⌘2) to rewrite whatever you copied, have any selected text read aloud (⌘4), or open an AI chat that works with your Calendar, Gmail, Tasks, and Trello (⌥Space).

Bring your own API keys — Gemini, and optionally GPT, Grok, or Claude — or run fully offline with local Whisper. No account, no subscription, no backend. Open source (AGPL-3.0).

▶️ Watch the full demo on YouTube · Website: whispershortcut.com · Made by Magnus Gödde

Download

⬇️ Get WhisperShortcut on the Mac App Store — the easiest way to install, with automatic updates.

• Prefer a direct download? Get the latest signed .dmg from GitHub Releases.
• Cloud features use your Google Gemini API key and, optionally, an xAI API key (Grok chat and TTS), an OpenAI API key (GPT-5.x chat, transcription, GPT Audio Dictate Prompt, TTS), or an Anthropic API key (Claude chat). Offline Whisper needs no key at all.

Features

• Dictate: Record speech; the transcription inserts at the cursor when auto-paste is on, and is always copied to the clipboard. Use Gemini, OpenAI, or any audio-capable model on OpenRouter, your own OpenAI-compatible server (LiteLLM, Azure, …), or an on-device model offline. Offline, Parakeet Ultra is the recommended model: 25 European languages, German and English included, transcribed in a fraction of a second after Stop (about 0.1 s for a sentence, under a second for a minute without Glossary terms) at the accuracy of Whisper Large v3 Turbo, ~700 MB download. On-device models write the German layout commands "Doppelpunkt", "neuer Absatz" and "neue Zeile" as ":", a blank line and a line break; Whisper models stay available for other languages. Temperature and thinking effort are configurable for cloud models. Longer recordings start transcribing while you still speak — Gemini, OpenAI, Grok, and on-device Whisper — so pressing Stop only waits for the last chunk (Parakeet transcribes the whole recording after Stop, which is faster still). If a chunk fails, the app falls back to transcribing the full recording.
• Add Selection to Glossary: Select a correctly spelled term anywhere — your practice software, a document, an email — and use the menu item or a shortcut you set in Settings → General (it has no default shortcut; direct-download build only). It is appended to the Glossary verbatim, with a duplicate check. No model is involved, which makes it the way to grow the Glossary while Offline Mode is on, where the model-driven learning paths (Smart Improvement, the typed-text learner) do not run.
• Offline Mode: One switch (Settings → Privacy & Permissions, also offered during onboarding) that makes the app device-local: dictation runs on an on-device model (Parakeet Ultra or Whisper), requests the app itself builds are blocked at the network layer, and no transcript, prompt or audio sample is written to the usage log. Requests to your own machine or local network still work, so a Whisper server or Ollama on your network stays available. Downloading a Parakeet, Whisper or MLX model from Hugging Face still works (FluidAudio and WhisperKit use their own URLSessions, which the Offline Mode guard does not wrap — that download carries no content of yours; once downloaded, Parakeet loads with FluidAudio's own network switch shut and never re-downloads on its own; a failed load is reported, and Delete + Download in Settings is the repair). Dictate Prompt keeps working through an in-process MLX model (Qwen3 4B Instruct, downloads itself, no server needed) or a local Ollama / LM Studio server if you prefer to run your own. Offline MLX and HTTP-local models read plain text, so they take the text to edit from your clipboard — in the App Store build, copy the text yourself (⌘C) before you start dictating, since that build cannot copy the selection for you. Dictate Prompt also sends no earlier turns as history while it is on, so a note from the previous patient never travels with the next request. It also decodes greedily (temperature 0), so the same dictation is structured the same way every time, and checks every reply word by word against your dictation: words in the result that you did not dictate (headings, punctuation, segment formatting like L4/L5 and simple inflections aside) are listed in a "Not in your dictation" warning — shown even with popups off — while the text itself is pasted unchanged. Chat can run on the same offline MLX models; Read Aloud uses on-device macOS voices. Smart Improvement and the Google and Trello integrations have no on-device equivalent and stop working while it is on. Built for regulated dictation — patient findings, case notes — where "the recording never leaves this device" has to hold whatever else is configured.
• Anonymous usage statistics (opt-in, off by default): A switch in onboarding and Settings → Privacy & Permissions that, when you turn it on, sends a daily summary of counts to the developer — how often features were used and whether they worked, failure classes, which built-in models ran. Never transcripts, prompts, replies, audio, the apps you paste into, or any identifier. "See exactly what is sent" shows the exact JSON; turning it off deletes anything queued. Unavailable in Offline Mode. The receiving server's code is in server/telemetry/.
• Auto-paste: Insert the result at the cursor via simulated ⌘V (Settings → Clipboard Behavior). Off by default; needs the Accessibility permission; direct-download only — the App Store build copies to the clipboard instead. Turn on Restore clipboard alongside it for a non-destructive paste: whatever you had copied before dictating goes back on the clipboard right after the text is pasted.
• Copy Last Transcription: Every dictation result stays available in the menu bar — one entry re-copies the most recent transcription, and a Recent Transcriptions submenu holds the last five. Use it when an auto-paste landed in the wrong window, or when a later copy overwrote the clipboard.
• Dictate Prompt: Speak an instruction that edits the selected text, for example "make this shorter" or "translate this to English". With nothing selected, it writes what you dictate or ask for instead (for example "write a reply saying I can come on Friday", or a dictated note shaped by your Dictate Prompt system prompt, such as a fixed Anamnese / Befund / Therapie format) and inserts it at the cursor, without earlier turns from the conversation. Supports Gemini and OpenAI audio-input models, in-process offline MLX models (no server), a local Ollama / LM Studio server, or your own OpenAI-compatible server (the same one Dictate and Chat use); optional screenshots can be included with the prompt. With Gemini and a connected Google account, Trello or shared folder, it can look things up while it writes (read-only: your calendar, tasks, email, Trello cards, shared files), for example "reply and offer my free slot on Thursday"; switch this off in Settings → Dictate Prompt. While recording, the pill grows into a card: its header shows what the run will edit (the selected text, or a warning that nothing is selected and it will write new text), then your quick prompts — Control-1 to Control-9, or ↑/↓ and Return, runs one without speaking. By default these are the instructions you repeat most; in Settings → Dictate Prompt → Quick Prompts you can define your own list (up to nine, in your order) and choose whether your most-used instructions still appear below it. Type your own instruction into the field under the list and press the shortcut again (or Return) to run it. Return on an empty field does the same as ✓: it stops and uses what you said.
• Read Aloud: Press the shortcut on any selected text to copy it and read it aloud with Gemini, OpenAI, xAI, or on-device macOS voices. Playback starts after the first sentence or two is synthesized (typically a few seconds) while the rest streams in behind it, so you do not wait for the whole text. Markdown and links are stripped before synthesis, an optional Smart Rewrite pass (run by your chat model) cleans up code, logs or messy notes (plain prose skips it, saving the extra round trip), and playback speed is configurable. While it reads, a player pill at the bottom of the screen offers Stop, Pause / Resume, ±10 s skip buttons, a draggable progress bar with elapsed / total time, and a speed button that steps through 0.75×–2× live (the chosen speed is kept as the new default); pressing the shortcut again also stops. In Offline Mode the macOS voice is selected automatically.
• Screenshot: Capture the screen from the menu bar and optionally attach it to Dictate Prompt or chat, or save captures to a folder. Click instead of dragging a rectangle to capture the whole screen.
• Chat: Use a persisted multi-session chat window with Gemini, Grok, OpenAI, Claude (Anthropic), any chat model on OpenRouter, or offline MLX models, screenshots, image attachments, slash commands, optional web grounding, and per-session reasoning depth. Share a folder with /folder and the chat can read it — including the AGENTS.md / CLAUDE.md files and the rules and skills under .agents/, .cursor/, or .claude/ you already keep there, which are loaded into every message automatically so the chat works from your own context. Turn on file editing in Settings and it can write notes back into that folder too. Grok models additionally search X.com posts, which makes them the best pick for opinions, trends, and breaking social-media chatter — and /x @handle narrows that search to the accounts you care about.
• OpenRouter in Chat: Pick OpenRouter in the chat model picker (or type /openrouter), then choose the model in Settings → Chat from OpenRouter's live list, grouped by vendor with rough prices — no URL or slug to type, though "Custom slug…" still takes anything. It uses the OpenRouter account connected in Settings → Accounts, the same one Dictate uses, so there is no second key. Web search and image attachments are not available through OpenRouter in Chat.
• ChatGPT plan in Chat: Chat on your ChatGPT plan, no API key. GitHub download only: click Continue with ChatGPT in Settings → Accounts and sign in once. Pick ChatGPT plan in the chat model picker (or type /chatgpt), then choose the model in Settings → Chat from the list your account offers. Requests count toward your plan's usage limits; you can see them and set a limit for WhisperShortcut in ChatGPT Settings → Usage. Text and image attachments work. Web search and connected services (Google, Trello, mail) don't run on the plan yet. Dictation can't use the plan either, because OpenAI doesn't allow ChatGPT plans for transcription in other apps. Not in the App Store build yet.
• Your own server (LiteLLM, Azure OpenAI, Vertex AI, or any OpenAI-compatible endpoint): Run Dictate, Dictate Prompt and Chat through a server you control instead of a vendor the app picked — LiteLLM, OpenInference, a self-hosted server, or your own Azure OpenAI / Microsoft Foundry resource or Google Vertex AI project. Pick Own server in any of the three model pickers and enter one base URL (up to /v1, e.g. http://localhost:4000/v1 for LiteLLM) and that server's API key; the other two tabs then show it as set up instead of asking again. The app adds /audio/transcriptions for Dictate and /chat/completions for Chat; you name the speech model and the chat model separately (on Azure: your deployment names). Dictate Prompt transcribes your instruction on that server first, then sends the text to its chat model. One-click presets fill in the URL shape, and optional extra headers go with every request. A separate full Dictate URL can still be set under Advanced, for a speech server that does not follow the /v1 layout. The key is only ever sent to that server. Azure is detected from the URL and its key is sent the way Azure expects (api-key, not a bearer token), a bare Azure resource URL is expanded to /openai/v1, and an api-version is filled in for a classic deployment URL that omits it. Requests go straight from your Mac to that endpoint, in the region your resource or project runs in, under your own Microsoft or Google contract — no server of ours is involved. That is a statement about where inference runs and who your data-processing agreement is with; it is not a certification of this app, and whether it satisfies a professional confidentiality duty is a call for you and your counsel. Vertex takes a short-lived gcloud auth print-access-token value as the key, so it has to be pasted again about hourly; Azure keys do not expire. For dictation that never leaves the Mac at all, use Offline Mode instead.
• YouTube videos in chat: Paste a YouTube link into the chat and a Gemini model actually watches the video instead of guessing from search results. Link a moment (&t=1h50m10s) and it analyses a ten-minute window around it — the sensible way to ask about one passage of a long podcast. Without a timestamp the whole video is sent; if it is too long for the model, the opening ten minutes are used and the answer says so. Video analysis is Gemini-only: other providers cannot open YouTube links.
• Google integrations: Connect a Google account so chat can work with Calendar, Tasks, and Gmail through controlled local tools.
• Trello integration: Connect Trello so chat can list boards, lists, and cards and create, move, update, or archive cards.
• Mail accounts (IMAP): Ask the chat to connect any IMAP mailbox (IONOS, GMX, web.de, iCloud, Posteo, mailbox.org, Strato, your own domain), for example "Connect my mailbox [email protected]". The chat shows a secure password field; the password is checked against the server, stored in your Keychain and never sent to the AI model. Chat can then search and read those mailboxes, read-only: nothing is marked as read, moved, deleted or sent. Remove accounts in Settings → Accounts → Mail Accounts. Outlook/Hotmail are not supported (Microsoft allows sign-in only through Microsoft); Gmail goes through the Google connection.
• Live Meeting: Record meetings in chunks (online with headphones too), transcribe them as they complete, take live notes into the chat as the meeting goes on, ask the chat about anything said so far, and save meeting files locally. Models and timing are in Settings → Meetings.
• Claude & other AI apps: Turn on in Settings → Claude & AI Apps and click Connect next to Claude Code, Claude Desktop or Codex (WhisperShortcut writes the app's settings itself; macOS asks once for access to that folder), or copy the setup by hand. Each card then shows whether the app has connected, and warns when it holds the read-only key although you allowed changes. ChatGPT itself can't reach apps on your Mac, so use Codex. Connected apps can read your meeting transcripts, notes and summaries, including the meeting that is recording right now. The app fetches only what is new since its last look. If you allow it, the AI app can also improve your setup from what it already knows about you: add names and terms to the glossary, rewrite your Dictate Prompt instructions and writing style profile, create or edit commands, and (with "Save usage data" on and a second switch) look at your recent dictations to find out why one went wrong. Choose "Suggest changes for me to approve" (each change opens in a review window) or "Make changes directly" (with Undo in Settings). Dictation and Chat instructions always wait for your approval. When the AI app finds a problem no setting can fix (the instructions already forbid it, or the mistake is in the app itself), it saves a problem report instead of piling on another rule: it opens in a window where you can edit out anything private and then open it as a GitHub issue, or discard it. Nothing is sent unless you submit the issue yourself. In Claude Code, /whisper-shortcut:tune_whisper_shortcut runs the built-in "tune my setup" recipe (focus prompts tidies instructions that grew too long). AI apps can also read and change WhisperShortcut's settings (models, shortcuts, behaviour) through get_settings/update_settings, within the same access level. Local to this Mac, protected by an access key (a separate one for changes), and switched off while Offline Mode is on.
• Welcome Tour: The guided setup that opens on first launch (permissions, a provider key or the offline path, a first dictation to try). Reopen it any time from Welcome Tour… in the menu bar menu or Settings → About; while setup is unfinished the menu shows Finish setup… at the top instead.
• Send Feedback: Reach the developer straight from the app — a Send Feedback entry in the menu bar (WhatsApp, email, or a GitHub issue), buttons in Settings → About, a Contact Support button on every error popup, and /feedback in chat, which attaches the end of the conversation. Report a Problem with Last Dictation… at the top of the Send Feedback menu opens your last dictation together with the transcription model, the date, whether a glossary echo was removed and which glossary terms appear in the text (never the rest of your glossary), so a wrong dictation can be reported without looking anything up. You can edit or delete any of it, then send it by WhatsApp or email, or copy it. Share Usage Report in Settings → About adds a summary of how the app actually behaved for you — how many dictations and chats, which models, how often a result had to be redone — with no transcripts, prompts, replies, or audio in it, shown to you in full beforehand. Every route prefills the app and macOS version, and nothing is sent until you press send.
• Update notices (direct-download build): The GitHub build checks once a day for a new version (Settings → About → Updates, with Check for Updates… and a switch to turn the daily check off). A new version shows a notice with its release notes and an Install Update button; nothing is downloaded or installed until you click it, so a practice Mac never changes unannounced. Updates are signed (EdDSA) and verified before installing. The check is allowed in Offline Mode — it is the only request that leaves the Mac, fetches the release list from github.com and sends only the app's name and version. The App Store build updates through the App Store instead.
• Smart Improvement: Let the app improve system prompts, user context, and the Glossary automatically from usage logs. For the Glossary it only ever adds: lines you wrote, including corrections like Bachata (not "Batchata"), are never removed, and when your transcripts keep misspelling a glossary term it proposes that correction for you to accept. A Scorecard in Settings → Smart Improvement shows whether an accepted change helped (rejected spellings, Dictate Prompt follow-up fixes, dashes added, retries), counted on your Mac from the local usage log. Prompt editors save as you type, and a customized prompt is backed up to system-prompts.md.bak before each change; if the saved prompts cannot be read, the app says so at launch instead of falling back to the defaults silently.
• Writing Style: Dictate Prompt drafts replies and messages the way you write them instead of in assistant prose. The app keeps a short profile per context (Email, Messenger, Work Chat, Default: your greetings, closings, Du/Sie, typical length, phrases you never use) plus a pool of messages you actually wrote, and adds a few matching examples to Dictate Prompt based on the app you are writing in. It learns by itself once you turn it on: what you dictate into Mail, Messages, WhatsApp, Signal, Telegram, Slack or Teams is kept as an example for that context, and with the Google connection your Gmail sent mail is imported right away and then once a week. When about 20 new messages have come in, the Smart Improvement model drafts an updated profile and shows it for review before it is saved; you can also edit it anytime, or add examples by hand in Settings → Smart Improvement → Writing Style → Add more manually. Off by default. Profile and examples are stored in the app's data folder on your Mac; when the feature is on, the profile and a few of your messages are sent with each Dictate Prompt request to your Dictate Prompt model. Local (offline) Dictate Prompt models do not get them, because small models apply the examples even to translate or correct instructions. Style facts you asked Chat to remember (for example "only short hyphens") also reach Dictate Prompt with cloud models.

Requirements

• macOS 15.5 or later
• Xcode 16.0 or later for development
• Google Gemini API key for cloud transcription, Dictate Prompt, chat, TTS, Smart Improvement, and live meetings
• Optional xAI API key for Grok chat models and Grok Voice TTS
• Optional OpenAI API key for GPT-5.x chat, OpenAI transcription (GPT Transcribe, GPT-4o Transcribe), GPT Audio Dictate Prompt, and GPT-4o mini TTS
• Optional Anthropic API key for Claude chat models
• Optional OpenRouter account — connect it with one click during onboarding or in Settings → Accounts (no API key to copy, and the flow creates the account if you do not have one; the same connection covers Dictate and Chat), or paste a key manually
• Optional Google account connection for Calendar, Tasks, and Gmail tools
• Optional Trello Power-Up API key and token for board, list, and card tools
• Optional IMAP mailbox password (stored in the Keychain) for read-only mail search

Offline dictation (Parakeet Ultra or Whisper) works without an API key after downloading a local model in Settings. Without any cloud key, Dictate Prompt and Chat use the offline MLX model (Qwen3 4B Instruct, ~2.3 GB) on Apple Silicon — the onboarding's offline path downloads it in the background. On Macs with 16 GB of RAM or more, Chat can also use Qwen3.5 9B (~5.6 GB, slower but more knowledgeable; Chat only, /mlx9b). Adding a key before you have used the offline model moves them back to your provider's model; once you have used it (or turned Offline Mode on), they stay offline until you pick another model.

Installation

1. Download the latest .dmg from Releases.
2. Open the DMG and drag WhisperShortcut.app into /Applications.
3. Start WhisperShortcut from Applications.
4. Open Settings from the menu bar app and add your Google Gemini API key if you want cloud features.
5. Grant microphone and accessibility permissions when macOS asks.

Common Workflows

Default menu bar shortcuts (all configurable in Settings → General):

Action	Default shortcut
Dictate	⌃⌥1
Dictate Prompt	⌃⌥2
Screenshot	⌃⌥3
Read Aloud	⌃⌥4
Chat	⌥Space
Settings	⌃⌥0

Installs from before these defaults keep ⌘1–⌘4 and ⌘0. Add Selection to Glossary has no default shortcut; set one in Settings → General. Every shortcut can be changed in Settings → General, and the in-app Chat always sees your current bindings.

Press Stop in the menu bar (or use the active mode's shortcut again) to cancel recording, TTS playback, or in-flight processing.

To change a shortcut, open Settings → General, click Record next to it and press the combination once. Any key works with at least one of ⌘/⌥/⌃, and F1–F20 can be bound on their own, without a modifier — that is the binding to use for a programmable (QMK/VIA) keyboard with a dedicated dictation key.

Fn (Globe) key (direct-download build only): Press Fn once to start recording, press it again to stop. It is on by default when macOS leaves the key free (System Settings → Keyboard → “Press 🌐 key to” → “Do Nothing”); otherwise turn on Also dictate with 🌐 Fn in Settings → General, under Keyboard Shortcuts, and the app shows how to free the key so macOS does not also react to it. It needs the Accessibility permission — the same one auto-paste uses; onboarding asks for it once for both.

Dictation

1. Configure a Dictate shortcut in Settings → General.
2. Choose a Gemini, OpenAI, OpenRouter, own-server, or Whisper transcription model.
3. Press the shortcut (or the Fn key, if you turned that on), speak, then stop recording.
4. The transcription inserts at the cursor when auto-paste is on (Settings → Clipboard Behavior; off by default; direct-download only). It is always copied to the clipboard as a backup.

Longer recordings (roughly ten seconds and up) start transcribing in the background while you speak, on Gemini, OpenAI, Grok, and on-device Whisper. Pressing Stop only waits for the last chunk. If any chunk fails, the app transcribes the full recording instead, so you still get a complete result.

Accuracy tuning (Settings → Dictate, cloud models only):

• Temperature — how literally the model reproduces what it heard. 0.0 (the default) is verbatim. The models' own default is 1.0, which is what the app sent before this setting existed and the most likely source of invented or swapped words.
• Thinking effort (Gemini only) — how long the model may reason before transcribing. Minimal is the default; raising it can help with hard audio, accents, and unusual vocabulary. On Flash-Lite the latency cost is close to zero; on Pro it roughly doubles. Gemini 3.8 Flash, Gemini 3.1 Pro, and Gemini 4 Argon cannot run below Low and are clamped to it.

Which transcription model should I pick? All of them work; they differ in speed, price, and how they behave on hard audio. Measured on the same recordings in September 2026 — latency is the median of 10 interleaved runs from one machine, so treat it as a ranking, not a guarantee:

Model	Latency (1.3 s / 8.2 s / 21.3 s of audio)	Cost per minute	Notable
Grok Speech-to-Text	0.39 s / 0.77 s / 1.33 s	low	Fastest on short and medium takes; empty on silence
GPT Transcribe	0.74 s / 0.86 s / 1.30 s	$0.0045 flat	Default and recommended; fastest on longer takes; empty on silence; best glossary of the cloud models
GPT-4o Mini Transcribe	0.72 s / 0.85 s / 1.30 s	~$0.003	Cheapest cloud option at OpenAI; shuts down 2027-02-26
GPT-4o Transcribe	0.74 s / 1.03 s / 1.63 s	~$0.006	Follows Dictation-prompt instructions; shuts down 2027-02-26
Gemini 3.1 Flash-Lite	1.01 s / 1.17 s / 1.48 s	~$0.001	Default if you only have a Gemini key; best glossary of the Gemini Lite tiers
Gemini 3.5 Flash-Lite	0.96 s / 1.20 s / 1.40 s	~$0.001	See the silence caveat below
Whisper (offline)	depends on your Mac and model size	free	Runs locally, nothing leaves your machine

Which offline Whisper model? Whisper Large v3 Turbo (~1.6 GB) is the recommended one: same accuracy as Large v3, roughly half the download and several times faster. Base (140 MB) is the smallest download if you just want to try offline dictation; Tiny and Base both make mistakes a transcript you intend to keep will have to be corrected for. Small (460 MB) sits in between. Medium and Large v3 are no longer offered — turbo is more accurate than Medium at the same size and matches Large v3 at half of it — but if you already downloaded one it stays selectable and deletable. Put names and jargon in the Glossary either way — that matters more than model size.

You do not have to manage the download. Selecting an offline model downloads it and loads it in the background, with progress shown in the model list. If you dictate before it is ready, the recording is kept and transcribed as soon as the model is — the app never quietly falls back to a cloud model you did not pick. The large models load on the GPU rather than the Neural Engine: the ANE needs CoreML to compile the model first, which for Large v3 Turbo ran for over 14 minutes here without finishing, while the GPU loads the same model in about 6 seconds. Tiny and Base compile quickly and keep the ANE.

Recommendations by what you care about:

• Lowest latency — Grok Speech-to-Text on short and medium recordings; GPT Transcribe is as fast once the take is longer than about 20 seconds.
• Cheapest cloud — Gemini Flash-Lite, roughly 4× cheaper per minute than GPT Transcribe. Gemini bills audio and output tokens, so a long transcript costs more; GPT Transcribe bills only recording length, which makes it easier to predict.
• Privacy — an offline Whisper model. No audio leaves your Mac.
• Names and jargon spelled right — put them in the Glossary first; that matters more than the model. GPT Transcribe reproduced glossary terms more reliably than any other cloud model in our tests; among the Gemini Lite tiers, 3.1 Flash-Lite still beats 3.5 Flash-Lite.
• A Dictation prompt with formatting rules — use a Gemini model or GPT-4o Transcribe. GPT Transcribe and Grok are pure speech-to-text and ignore instructions in the prompt.

A note on silence. If a recording is silent or unintelligible, some models invent a plausible-sounding sentence built from your Glossary instead of returning nothing. WhisperShortcut filters implausible transcripts, but the filter cannot catch every case: in our tests Gemini 3.5 Flash-Lite leaked invented sentences on most silent takes, Gemini 3.1 Flash-Lite and GPT-4o Mini Transcribe leaked on some, and GPT Transcribe and Grok returned nothing at all. If you often start recording before you start speaking, that is worth knowing when picking a model.

GPT Transcribe (OpenAI): OpenAI's current transcription model, billed by audio duration rather than tokens, and the replacement for GPT-4o Transcribe and GPT-4o Mini Transcribe (both shut down 2027-02-26). It is a pure speech-to-text model, so it ignores the Dictation system prompt; your Glossary still applies and is sent as keyword hints, which in testing was the more reliable way to get names and product terms spelled right. Unlike the GPT-4o transcription models, it returns an empty transcript on silence instead of echoing the glossary back.

OpenRouter: select the OpenRouter transcription model, then click Connect OpenRouter Account in Settings → Accounts (Settings → Dictate links there from the model picker). That opens OpenRouter in a browser sheet where you sign in — or create an account, if you do not have one — and approve; the app receives its key directly, so there is nothing to copy and paste. You pay OpenRouter for what you use, and can top up or revoke access from your OpenRouter dashboard at any time. If you already hold a key, "Enter an API key manually instead" still accepts it. The same connection covers chat as well: pick OpenRouter as the chat model and no key is needed there either. The model list in Settings → Dictate is fetched live from OpenRouter and filtered to models that actually accept audio, with rough prices shown, so there is no slug to look up or memorise — pick one from the menu. New models appear as OpenRouter adds them, without an app update. "Custom slug…" still lets you type anything, for models the list does not cover. OpenRouter has no dedicated transcription endpoint, so the audio is sent as a chat message; that means your Dictation system prompt and Glossary apply here, unlike the OpenAI and self-hosted transcription endpoints.

Dictate Prompt

1. Copy text you want to edit.
2. Press the Dictate Prompt shortcut.
3. Speak an instruction, such as "turn this into bullet points".
4. The edited result inserts at the cursor when auto-paste is on, and is always copied to the clipboard.

Optional: capture a screenshot (the Screenshot shortcut or chat /screenshot) before or during the prompt when screenshot-in-prompt mode is enabled.

Read Aloud

1. Select text in any app.
2. Press the Read Aloud shortcut.
3. The selection is copied and read aloud with your chosen TTS model and voice.
4. A player pill at the bottom of the screen lets you stop (✕), pause / resume, skip ±10 s, drag the progress bar to any position, or change the speed while it reads.

Use Settings → Read Aloud to pick the TTS provider, voice, Smart Rewrite, and playback speed. Chat replies can also be read aloud from the message actions.

Screenshot

Press the Screenshot shortcut to capture the screen. Captures can be attached to the next Dictate Prompt or chat message, or saved to a folder when that option is enabled in Settings → Screenshot.

To capture the whole screen instead, press the Screenshot shortcut and just click anywhere without dragging: the screen you clicked on is copied to the clipboard. Esc still cancels.

Chat

Open the chat window from the menu bar or its configured shortcut. Chat sessions are stored locally.

Core slash commands:

• /new — start a new chat
• /screenshot — attach a screenshot to your next message
• /attach — open the file picker for PDFs, images, or text
• /folder — share a folder so the chat can list, read, and search files in it (dropping a folder onto the chat window does the same)
• /workspace — limit this chat to one of the shared folders (e.g. /workspace notes); all restores every folder, off drops file access for this chat
• /model — switch model: type /model and pick from the list, which filters as you type (e.g. /model opus)
• /think — set reasoning depth for this chat (minimal, low, medium, high, or default; on Grok and GPT the default is low for fast answers, use high for research)
• /x — Grok only: limit X search to specific accounts for this chat (e.g. /x @karpathy @simonw); /x off searches all of X again. Set a default under Settings → Chat
• /settings — open Settings
• /pin / /unpin — keep the window open or close on focus loss
• /meeting — start or stop live meeting recording
• /copy — copy the chat history as Markdown

Your own commands

Put a Markdown file into the app's commands folder (Settings → Chat → Commands → Open Commands Folder, or New Command… for a commented template) and it becomes a slash command: report.md is /report. Its text is sent to the selected chat model as your message, offline models included; text you type after the name (/report focus on next steps) is added as extra instructions. In a meeting chat the model also sees the full transcript, so a command like "write the minutes in our format" works with one click. Optional header lines set the button label, a description, and the scope (meeting, chat, or both); meeting commands also get a button above the meeting chat's message field. The chat shows the command as a compact chip, with the full instruction one click away. Settings lists every command it loaded and says which files it could not read and why.

/feedback opens a message to the developer with the end of the current chat quoted, so a problem you were just discussing does not have to be described twice.

Typing / lists commands only; models live behind /model. For speed, the model shortcuts still work when typed in full: /gemini, /grok, /gpt, /openai, /claude, /anthropic, /mlx, and per-model aliases such as /gemini31flashlite. Gemini models use your Google API key, Grok models use your xAI API key, OpenAI models use your OpenAI API key, and Claude models use your Anthropic API key.

Connect Google or Trello in Settings → Accounts to unlock the corresponding chat tools. Creating or deleting a calendar event, changing a Trello card, or opening a URL asks for confirmation first.

Workspace folders and context files

A folder shared with /folder, by dropping it on the chat window, or in Settings → Chat → Workspace Folders stays shared for every chat until you remove it. Inside it the chat can list directories, read text files, and search by name or content — read-only, and nothing outside those folders is reachable.

If a shared folder contains the agent-context files you already keep for other AI tools, they are loaded into every message of every chat automatically, the same way Cursor and Claude Code load them:

• AGENTS.md, CLAUDE.md, GEMINI.md, or .cursorrules at the folder's top level
• rules under .agents/rules/, .cursor/rules/, and .claude/rules/
• each skill's SKILL.md under .cursor/skills/, .agents/skills/, and .claude/skills/

Point the chat at a notes folder that describes who you are and how you want to be helped, and it works from that context without being asked. Anything reachable under more than one of those paths — CLAUDE.md symlinked to AGENTS.md, .cursor/skills and .claude/skills both pointing at .agents/skills, or plain copies — is loaded exactly once. Whatever those files reference — a dossier folder, other notes — is not preloaded; the chat opens it with its file tools when a question calls for it.

A folder stays shared for every chat, which is usually what you want — but not always. /workspace notes limits the current chat to the folder whose path matches "notes": only its files are searchable and only its context files are loaded. /workspace on its own reports what the chat is using and lists the alternatives, /workspace all restores every folder, and /workspace off turns file access and context files off for this chat. The setting belongs to the chat and survives restarts; other chats are unaffected. It cannot grant a new folder — macOS only lets a sandboxed app take one through the picker or a drop.

By default the chat can only read. Turn on Let the chat create and change files in these folders in Settings → Chat → Workspace Folders and it can also write: create a file, append to one, or replace an exact piece of text in one. It cannot delete or rename anything, it refuses to write into .git, node_modules, or credential directories, and before it replaces or edits a file the previous content is copied into the app's WorkspaceBackups folder and kept for 30 days. While the switch is off the write tools do not exist for the model, so it says so instead of pretending to have saved something.

Hidden entries are visible to the file tools, so dot-directories like .cursor, .claude, or a personal .ai folder can be explored and read. Caches, build output, version-control internals, and credential directories (.git, node_modules, .ssh, …) are skipped.

Live Meeting

Type /meeting in chat to start and stop live meeting recording. Audio is rotated into chunks, transcribed, and appended to the meeting transcript. Saved transcripts live in the app's Application Support folder.

Online meetings work with headphones. Your microphone can't hear the other participants in your headphones, so the app records what your Mac plays as well and mixes it in. It decides from the output device, and follows it when you switch mid-meeting:

• Headphones or headset → the Mac's sound is recorded next to your microphone.
• Speakers → microphone only: it already hears the others through the speakers, and mixing in the Mac's sound would record them twice.

The meeting bar says which one is active (Headset · microphone + Mac sound or No headset · microphone only). Click it to override the detection with With headset: microphone + Mac sound or Without headset: microphone only — needed for Bluetooth or USB speakers, which look like a headset to the app. The Mac's sound means everything your Mac plays (music, videos, notifications), not just the meeting app; only WhisperShortcut's own sound is left out. The first time, macOS asks for permission under Privacy & Security ▸ Screen & System Audio Recording; without it the meeting is recorded from your microphone only, and the meeting bar says so.

While a meeting runs:

• Live notes appear in the chat itself. Every minute or two the app appends one or two bullets covering what was just discussed, woven into the chat stream at the moment it was said — so you can see what is going on in the same column where you type. Earlier notes are never rewritten.
• The chat sees the entire transcript, not just the last few minutes, so you can ask about anything said since the meeting started. A line above the composer says exactly what the chat can currently see. When you send a question, the audio still sitting in the recorder is cut and transcribed first, so the answer covers what was said seconds ago too.
• Your own one-click commands above the composer: every command file meant for meetings becomes a button there (see Your own commands under Chat). The app ships none, so the bar stays empty until you add some.
• Ask about a moment: hover any note and press Ask to quote it into the composer instead of retyping it.
• Copy transcript in the meeting bar puts the raw transcript on the clipboard; right-click it to reveal the file in Finder. Copy transcript + chat next to it copies the transcript, the live notes, and every question and answer from the meeting chat, as one Markdown document.

While the meeting runs there is only the chat — the notes are already in it. Once a meeting has ended, its view has two tabs: Chat and Notes, where Notes holds the final summary. Chunks rotate faster while the chat window is on screen so the live view keeps up, and fall back to the configured interval when it is not.

Dictate and Dictate Prompt keep working during a meeting, and the menu bar shows which of the two recordings is running: 📝 for the meeting, 🔴 / 🤖 while you dictate on top of it. Stopping a meeting is not instant — the last chunk still has to be transcribed — so the meeting bar says Finishing… and the menu bar shows ⏳ until the transcript and summary are saved.

No connection, no lost meeting. If a part of the meeting can't be transcribed (offline, quota, the service is down), you get a popup right away, recording continues, and that part's audio is kept on your Mac. When the meeting ends it is tried again automatically; anything still missing stays available under Retry Meeting Transcription in the menu bar menu (hold ⌥ to show the kept audio in Finder). Recovered parts land at their original place in the transcript, and the summary is written once the transcript is complete.

Smart Improvement

In Settings → Smart Improvement, enable Save usage data (off by default) if you want the app to learn from your interactions. Then use Improve from usage or Generate with AI to review suggested updates to system prompts, user context, or the Whisper glossary before accepting them.

Build From Source

git clone https://github.com/mgsgde/whisper-shortcut.git
cd whisper-shortcut
bash install.sh

For development, build and restart the app with:

bash scripts/rebuild-and-restart.sh

Build prerequisites:

• Metal Toolchain: mlx-swift compiles Metal shaders, so Xcode needs the Metal Toolchain component (about 690 MB). Without it the build fails early with cannot execute tool 'metal'. Install it once with xcodebuild -downloadComponent MetalToolchain.
• Package plugin validation: mlx-swift ships a build plugin, so a plain xcodebuild needs -skipPackagePluginValidation. The scripts above already pass it.
• Tests need macOS 26.5: the test target's deployment target is macOS 26.5, while the app itself runs on 15.5 and later. On an older macOS, xcodebuild build works but scripts/run-tests.sh does not.

Useful scripts:

• scripts/rebuild-and-restart.sh: Build Debug, sync bundled docs, and restart the local app.
• scripts/logs.sh: Stream or filter app logs.
• scripts/create-release.sh: Create a tagged release.
• scripts/test-gemini-models.sh, scripts/test-grok-models.sh, scripts/test-openai-models.sh: Check provider model availability and basic responses.

Project Structure

• WhisperShortcut/: Swift source for the macOS app.
• WhisperShortcut/Docs/: User-facing markdown bundled with the app (mirrored from the repo README and data-directory docs on rebuild).
• WhisperShortcut.xcodeproj/: Xcode project and shared schemes.
• scripts/: Local development and release helper scripts.
• .github/workflows/release.yml: GitHub Actions workflow for signed, notarized release builds.
• plans/: Shared implementation plans and specs.
• .agents/skills/: agent skills (shared by Cursor, Claude Code and the in-app Chat); .cursor/: rules, commands, CODEMAP.md and CONTEXT-CONVENTIONS.md (the layout, shared with sabaki.dance).

Core files:

• AppState.swift: Central app state machine.
• MenuBarController.swift: Main app orchestrator.
• SpeechService.swift: Dictation, Dictate Prompt, and Read Aloud logic.
• ChatView.swift: Chat UI and view model.
• ChatTools.swift: ChatToolRegistry and local, Google, and Trello chat tools.
• TranscriptionModels.swift: Gemini, OpenAI, Whisper, and self-hosted transcription models.
• Settings/: Settings UI, defaults, and persistence.

Data And Privacy

WhisperShortcut stores settings, chat sessions, meeting transcripts, usage logs, short-lived Smart Improvement audio samples, and downloaded models on your Mac. API keys, OAuth refresh tokens, and Trello tokens are stored in Keychain.

With Offline Mode on (Settings → Privacy & Permissions), requests the app itself builds may not leave your Mac and the usage log is not written at all — no transcripts, prompts, replies or audio samples on disk. Offline model downloads still reach Hugging Face through FluidAudio's and WhisperKit's own URLSessions. Note that auto-paste needs the Accessibility permission and is therefore only available in the direct-download build, not the App Store one.

WhisperShortcut uses one canonical app data location so sandboxed and non-sandboxed builds see the same files:

~/Library/Containers/com.magnusgoedde.whispershortcut/Data/Library/Application Support/WhisperShortcut/

See the App Data Location section in privacy.md for what each subfolder contains.

License

GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for details.

Offline speech models are downloaded at runtime, not shipped in this repository: Parakeet Ultra by Moondream, a retraining of NVIDIA Parakeet TDT 0.6B v3, both CC BY 4.0, plus NVIDIA Parakeet CTC 110M for Glossary terms (CC BY 4.0), all downloaded as FluidInference's Core ML conversions and run through FluidAudio (Apache 2.0); Whisper models by OpenAI (MIT), run through WhisperKit (MIT).