Voice notifications for Claude Desktop and Cowork
Give Claude a long research task or a Cowork job and step away. When it's done, or stops to ask you something, Claude tells you out loud in one sentence. Free and open source.
What you hear
One short line, written by Claude itself, at the end of a reply that did real work:
- Done: “Trip planning. Booked options are in the doc, the Lisbon hotel is the cheapest.”
- Needs you: “Quarterly report. Should I use last year’s numbers for the comparison?”
- Error: “Inbox cleanup. I couldn’t reach the mail connector, nothing was changed.”
Quick chat replies stay silent on purpose. You hear Claude when there’s something worth stepping back for.
Set it up in the app
- Download Earpiece and open it. The first builds are unsigned, so macOS asks you to allow it once under System Settings → Privacy & Security → Open Anyway.
- Open Agents and click Connect next to Claude Desktop. It shows Connected when it’s done. Connecting only edits the file shown there, and keeps a backup.
- Quit and reopen Claude Desktop, so it starts the Earpiece server.
- Click Test voice at the top of the Overview page to hear it.
Agents
Earpiece listens to each agent in the way that agent supports. Connecting only edits the file shown, and keeps a backup.
Any other tool can talk to Earpiece with the command line: earpiece emit --agent my-tool --type turn_end --line “Build finished”. It shows up here once it has sent something.
The Claude Desktop card on the Agents page shows where the server is registered: an MCP server in ~/Library/Application Support/Claude/claude_desktop_config.json.
Make it yours in the app
| Setting | Where | What it does |
|---|---|---|
| Speak for this agent | Agents → Claude Desktop | Mutes Claude Desktop without disconnecting it. |
| Name Earpiece says | Agents → Claude Desktop | The name used when lines announce the agent. |
| Voice | Agents → Claude Desktop | A voice just for Claude Desktop, so you can tell it apart from your coding agents. |
| Say the agent’s name | Voice | Starts each line with the agent’s name instead of just the topic. |
| Quiet for a while | Quiet | Nothing is read aloud, but every update still shows in the notch. |
| Quiet hours | Quiet | Silence at night, with “Still say” to let “needs you” through. |
| API keys | API Keys | Optional Smallest.ai key for natural voices. No OpenAI key needed here. |
Only one line plays at a time across Claude Desktop, Claude Code and Codex.
Prefer the terminal?
Install from source and connect only Claude Desktop, then quit and reopen Claude Desktop:
git clone https://github.com/adissocrazy/earpiece.git
cd earpiece
node bin/earpiece.mjs install --only claude-desktop
npm link
earpiece testThe installer adds one entry under mcpServers, roughly like this, and backs up the file first:
{
"mcpServers": {
"earpiece": {
"command": "/path/to/node",
"args": ["/path/to/earpiece/bin/earpiece.mjs", "mcp"]
}
}
}Your other MCP servers are left alone. If your organisation set up its own Claude build with a separate settings folder, that one gets the server too. earpiece uninstall removes the entry, the same as Disconnect.
How it works: a small MCP server
Claude Code and Codex have hooks, so Earpiece listens to them. Claude Desktop doesn’t. Instead, Earpiece adds a local MCP server, earpiece mcp, to claude_desktop_config.json. It gives Claude one tool, earpiece_notify, and tells Claude to call it once, as the last step, when a reply:
| Status | When Claude sends it |
|---|---|
done | It finished multi-step work: tool calls, files, research, code. |
needs_input | It stops to ask you a question or needs a decision or approval. |
error | It couldn’t finish because something failed. |
Claude writes the sentence itself and adds a short topic name for the conversation, so you know which chat it was. The server runs on your Mac over stdio and talks only to the Earpiece app.
- Claude decides when to speak. With no hooks, Earpiece relies on Claude calling the tool at the end of real work. It usually does.
- No summary key needed. Claude already wrote the line, so nothing from the chat is sent anywhere for a summary. Your Mac’s voice reads it for free, or use a natural voice with your own key or Earpiece Pro.
What the server enforces
- Speakable lines only. Markdown and code are stripped, links become their domain, file paths their file name, and IDs and secrets are dropped. Lines are cut to about 25 words.
- No loops. The same update twice within a minute is skipped, and more than five calls a minute are refused, with a note telling Claude to call once per reply.
- Claude knows what happened. The tool result says whether the line was queued, or held back because Earpiece is off, in quiet mode or inside your quiet hours.
Questions
Does it work in Cowork?
Yes. The server is available to Claude in chats and in Cowork.
I added Earpiece but hear nothing.
Quit and reopen Claude Desktop so it starts the server, then give Claude a task with a few steps. A one-line answer is meant to stay silent.
Does my chat leave my machine?
No summary is needed, so the chat isn’t sent anywhere by Earpiece. If you use a natural voice (your own key or Pro), the one spoken sentence goes to the voice provider to be read aloud (through our server on Pro).