Voice notifications for Claude Code
Start a task in Claude Code and walk away. Earpiece says what happened, out loud, when Claude finishes, needs your permission or is waiting on you. Free and open source.
What you hear
One short line per event, spoken by your Mac or a natural voice. It starts with the project, so you know which session it means.
- Done: “checkout service. Refactored the cart drawer, all tests pass.”
- Needs permission: “api needs your permission to use Bash.”
- Waiting for you: “api is waiting for you.”
Without API keys, Earpiece speaks the first sentence of Claude’s final reply with your system voice. With an OpenAI key, or with Earpiece Pro, it writes a real one-line summary first.
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 Code. It shows Connected when it’s done. Connecting only edits the file shown there, and keeps a backup.
- Restart any Claude Code sessions that were already running, so they pick up the hooks. New sessions work right away.
- 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.
Make it yours in the app
| Setting | Where | What it does |
|---|---|---|
| Speak for this agent | Agents → Claude Code | Mutes Claude Code without disconnecting it. |
| Name Earpiece says | Agents → Claude Code | The name used when lines announce the agent. |
| Voice | Agents → Claude Code | A voice just for Claude Code, so you can tell it apart from Codex. |
| Minimum turn length | Agents → Claude Code | Shorter turns stay silent. 30 seconds by default. |
| Say the agent’s name | Voice | “Claude Code, api. Done…” instead of just the project. |
| 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. |
| Answer from the card | General | Approve or deny a tool request on the notch card. Off by default. |
| API keys | API Keys | Optional Smallest.ai key for natural voices, OpenAI key for summaries. |
Every session shows on the Overview page and in the notch, and only one line plays at a time. Keys and tokens are redacted before a line is spoken or sent for a summary.
Prefer the terminal?
Everything above also works from the command line. Install from source and connect only Claude Code:
git clone https://github.com/adissocrazy/earpiece.git
cd earpiece
node bin/earpiece.mjs install --only claude-code
npm link
earpiece test| Command | Same as |
|---|---|
earpiece voice <voice-id> --agent claude-code | Agents → Claude Code → Voice |
earpiece quiet 60 | Quiet for an hour |
earpiece quiet-hours 22:00-08:00 --allow needs_input | Quiet hours, still saying “needs you” |
earpiece answers on | General → Answer from the card |
earpiece agents | The session list on Overview |
earpiece uninstall | Disconnect for every agent, and puts your files back |
What it hooks
Earpiece adds four hooks to ~/.claude/settings.json. Each returns within milliseconds, so Claude never waits on it.
| Hook | What Earpiece does with it |
|---|---|
UserPromptSubmit | Marks the session as working and notes when the turn started. |
Stop | Speaks the summary when the turn ends. |
Notification | Speaks permission prompts and “waiting for your input”. |
PostToolUse | If the tool ran, you already approved it, so the pending permission alert is dropped. |
By default, turns shorter than 30 seconds stay silent, since you were probably watching. For every field these hooks receive, see Claude Code hooks explained.
Questions
I already have my own Claude Code hooks. Will they break?
No. Earpiece adds its own entries next to yours and backs up the file first. earpiece uninstall removes only what it added.
Does my code leave my machine?
Only if you add an OpenAI key or use Pro. Then the end of Claude’s final reply is sent to write the summary, with keys and tokens removed first. Without either, nothing is sent.