← All posts

Why Whisper mishears code words, and the fix

You dictate a prompt for Claude Code: “move the retry logic out of useSessionStore and into the stripe webhook handler.” What lands in the terminal reads “use session store” and “stripe web hook”. The sentence is right. The two words the agent needed to find in your code are wrong.

This post explains why speech recognition is good at English and bad at your repo, and what actually helps, from a vocabulary list to a clean up pass after transcription.

Why Whisper guesses at your identifiers

Whisper was trained on 680,000 hours of audio and transcripts collected from the web (Radford et al., ICML 2023). That is why it handles accents, background noise and fast talkers so well. It is also why it struggles with your codebase.

The decoder writes text one token at a time, picking what is most likely given the audio and the words so far. For “use session store” the likely answer is three ordinary English words, because that is how those sounds appeared in almost every transcript the model saw. Your hook, your service names and your internal tool were never in that data. The model is not mishearing you. It is spelling what it heard the way most people would.

Larger models guess better, a point we cover in how Whisper runs offline on a Mac. No model size knows your repo, though.

Three kinds of code word errors

Most mistakes in a dictated prompt fall into one of three groups. They need different fixes.

  1. Split or joined words. WhisperKit can come out as “whisper kit”, PostHog as “post hog”, pgbouncer as “PG bouncer”. The sounds are right, the word boundaries are not.
  2. Sound alikes. A rare name gets swapped for a common word that sounds close. Short tool names and acronyms suffer most, because there is little audio to go on.
  3. Shape. useSessionStore, stripe-webhook and MAX_DEVICES have casing and symbols you never say out loud. Speech has no camelCase, so no speech model can hear it. Something has to know the word exists.

The first two are recognition problems. The third is a formatting problem. A vocabulary list helps with all three, because it gives the system the exact spelling to aim for.

How a vocabulary list steers the model

Whisper accepts a short text prompt alongside the audio. OpenAI’s speech to text guide suggests using it to “pass a dictionary of the correct spellings” for words and acronyms the model gets wrong. Their Whisper prompting guide shows a list of made up product names fixing exactly the split word problem above: without the prompt the names came out broken into pieces, with it they came out as written.

The same guide is honest about the limits, and they shape how you should write the list:

  • Whisper “follows the style of the prompt, rather than any instructions contained within”. A list of words works. A sentence like “always spell it PostHog” does not.
  • The prompt is capped at 224 tokens, and when it is longer only the final 224 are kept. Users in a Whisper GitHub discussion found a hard surname came out right only when it sat near the end of the prompt.
  • The techniques “are not especially reliable”, and the prompt “will not override the model’s comprehension of the audio”. If you mumble, the list will not save you.

The guide’s second method is to post process the transcript with a text model that knows the correct terms. That catches what the prompt misses, including casing.

Checked on 17 October 2026 against the OpenAI speech to text guide and the Whisper prompting guide.

How to build a list that works

Treat the list like a config file you keep short on purpose.

  • Only words the model gets wrong. “Database” does not need to be there. pgbouncer does.
  • Exact spelling, exact casing. Write the word the way it should appear in your prompt.
  • Project words, not a dictionary. With a 224 token budget, fifty stale library names push out the five you use today. Prune when you switch repos.
  • Say it the way you always say it. If you say “the S3 bucket”, add S3, not “Amazon Simple Storage Service”.

A starting list for a web project might look like this:

useSessionStore
stripe-webhook
PostHog
pgbouncer
WhisperKit
MAX_DEVICES

Dictate one prompt that uses each word, read what came out, and add or drop from there. Ten minutes once beats correcting the same name in every prompt.

Where Akova fits

Akova is a menu bar app that transcribes with WhisperKit on your Mac and types the result at your cursor in any terminal, editor or chat box. Custom vocabulary is part of the free tier: you teach it your repo names, APIs and jargon once, and they come out spelled right. There is a walkthrough with a real project list in how to dictate prompts into Claude Code.

The post processing step is there too. Lifetime adds a Fix mis-hears mode and Prompt mode, which turns a rambling take into a structured prompt for your agent. Both run locally, on Apple Intelligence on macOS 26 or a local Ollama model on macOS 14 and 15. Every Pro feature is free for 7 days after your first launch, and the pricing section lists what stays free after that.

Your next step: open the repo you work in most, write down the five names you say every day, and dictate a prompt that uses all of them.