Install
- 1
Download and drag it to Applications
Apple silicon, macOS 12 or later. The download is about forty megabytes.
- 2
Open it, and let macOS ask you twice
Earshot is signed but not notarised, so the first open goes through Privacy & Security in System Settings, where an Open Anyway button is waiting for you.
- 3
Leave it to fetch the models
Around 800 MB the first time, kept in your home directory rather than in the app. It says so in the notch while it works, and you can carry on with the rest of the setup meanwhile.
- 4
Pick the key you hold to talk, then hold it and say something
The last step is a live one on purpose: you watch the words arrive before anything you care about depends on them.
Setup is reachable again afterwards from the menu bar, because permissions get revoked and agents get installed long after the first run.
What an agent can call
Agents reach Earshot through an MCP server inside the app bundle, registered for you during setup. Three tools, and no more than three. This is what each one puts in the notch.
ask_user(question, choices?)Speaks the question, opens the microphone, and blocks until you answer. Your words come back as the tool result, so the agent never has to end its turn to hear you. The panel turns cool the moment the floor is yours.
choices is optional and never read out. The agent phrases its own options into the question, and the list is only what your answer is matched against. Anything matching none of them comes back word for word, because an agent handed the wrong option confidently has no way of noticing.
speak(text)Says a short summary out loud. Meant for the end of a turn, not for reading code: anything longer than a couple of sentences is faster to read than to hear.
working(status)Puts a phrase in the notch without saying anything. It is silent, it costs nothing, and it is the whole difference between a long pause and a session that looks dead.
Settings
The menu bar holds all of it: the voice and its pace, the microphone, the hotkey, launch at login, and a button that speaks a sample so you can hear a voice before you commit to it.
Every setting is also an environment variable, and the environment wins, so a one-off EARSHOT_VOICE=supertonic/F1 beats whatever the menu last saved.
| Variable | Default | What it changes |
|---|---|---|
EARSHOT_HOME | ~/.cache/earshot | Models, settings and the socket. |
EARSHOT_VOICE | supertonic/M1 | Any id from the catalogue. |
EARSHOT_MODEL | the bundled gguf | By filename, inside $EARSHOT_HOME/models. |
EARSHOT_HOTKEY | Ctrl+Alt+Space | Push to talk. |
EARSHOT_MIC | system default | Device id, as listed in the Microphone menu. |
EARSHOT_REPLY | streaming | Or teleprompter. How a spoken reply is revealed. |
EARSHOT_SPEED | 1.0 | Speaking pace. Below one is slower. |
EARSHOT_STEPS | 16 | Denoising steps. Higher is steadier and slower. |
EARSHOT_VAD_THRESHOLD | 0.5 | How sure the detector has to be. Raise it in a noisy room. |
EARSHOT_VAD_SILENCE | 700 | Milliseconds of quiet that end a turn. |
EARSHOT_WAKE_THRESHOLD | 0.9 | How sure the wake word has to be. |
A bad value falls back to the default rather than being clamped to the nearest legal one, so a typo is never quietly a setting. That includes the hotkey: a combination that will not parse leaves you with the default rather than with no way into the app.
The words it always gets wrong
Every recogniser mangles the same handful of words for a given person, and no amount of speaking clearly fixes it. The menu opens a list, one rule per line, with an example already in it.
Corrections happen after recognition rather than inside it, so a rule that makes things worse is visible on screen and can be deleted.
Updates
Nothing to do. Each launch checks quietly, and a newer build is downloaded, checked against a signature and swapped in. The models sit outside the bundle, so an update moves about forty megabytes rather than eight hundred.
When something is wrong
It hears me, and nothing gets typed
Accessibility permission has been revoked, which macOS does quietly after some updates.
Open Setup from the menu bar. It names the missing permission and takes you to the right pane.
The microphone was never asked for
Almost always a damaged copy rather than a settings problem.
Move the app to the bin, download it again, and open the fresh one.
It transcribes the room
The voice detector is set for a quiet desk.
Raise EARSHOT_VAD_THRESHOLD above 0.5, and EARSHOT_WAKE_THRESHOLD too if you use hands-free. Both trade a little responsiveness for a lot of quiet.
It answers before I have finished talking
Your turn ends after a fixed run of silence, and 700 ms suits someone who thinks before they speak.
Raise EARSHOT_VAD_SILENCE until the pauses in the middle of your sentences stop counting as the end of them.
Something here wrong or missing? Tell us and we will fix it.