# Heads-up: spoken alerts for Claude Code on Mac > A free Mac plugin that says out loud when Claude Code finishes or needs you. Seven voices, quiet on calls and in Focus, volume capped on headphones. - Page: https://www.brandbakery.tech/products/heads-up - Last updated: 2026-10-25 Breadcrumb: [Home](https://www.brandbakery.tech/) > [Work](https://www.brandbakery.tech/work) > Heads-up ## At a glance - **Product:** Heads-up, by Brand Bakery - **What it is:** An MCP server and Claude Code plugin that speaks a short line on your Mac when Claude Code finishes or needs you - **Price:** Free, with no paid tier - **Platform:** macOS (Node.js 20+, Claude Code or Codex) - **Built in:** 20 alerts, 7 voices, 140 clips. No API key, no account - **Source:** https://github.com/abhishek207/headsup-mcp - **License:** GNU GPL v3 (https://www.gnu.org/licenses/gpl-3.0.html) - **npm:** https://www.npmjs.com/package/headsup-mcp ## Your Mac will tell you when Claude Code needs you. It speaks a short line when a task is done or Claude is waiting on you, so you can step away from the screen. Example, in the default voice: "Hello. I need your review." ## Seven voices, built in They all say the same line here, so you can compare them. They come with the plugin, so you don't need a key or an account. - Brian, American male (ElevenLabs) - Sarah, American female (ElevenLabs) - George, British male (ElevenLabs) - Alice, British female (ElevenLabs) - Charlie, Australian male (ElevenLabs) - Aditya, Indian male (Sarvam) - Priya, Indian female (Sarvam) ## Twenty things it can say Claude picks the one that fits. Every line starts with “Hello.” and a short pause. Press a line to hear Brian say it. | Group | Status | Spoken line | | --- | --- | --- | | Needs you | review | I need your review. | | Needs you | feedback | I need your feedback. | | Needs you | input | I need your input. | | Needs you | approval | I need your approval to continue. | | Needs you | question | I have a quick question for you. | | Needs you | blocked | I'm stuck, and I need your help. | | Needs you | sign_in | I need you to sign in. | | Needs you | reminder | I'm still waiting on you. | | Finished | completed | I've completed the task. | | Finished | tests_passed | All the tests are passing. | | Finished | deployed | The deployment is live. | | Finished | pr_ready | The pull request is ready. | | Finished | next_task | I'm ready for the next task. | | Problems | error | Something went wrong. Please take a look. | | Problems | tests_failed | Some tests are failing. | | Problems | deploy_failed | The deployment failed. | | Problems | limit_warning | I'm close to my usage limit. | | Problems | limit_reached | I've hit my usage limit. | | Updates | long_task | This will take a while. I'll let you know when it's done. | | Updates | progress | Quick update. I'm still working on it. | You can switch any of them off on the settings page. With your own voice key you can rewrite them too. ## When it stays quiet Before each alert, Heads-up checks six things. If any of them is true, it skips the alert and tells Claude why, so Claude doesn't try again. - You used the keyboard or mouse in the last 60 seconds. You're already at the desk. The 60 seconds is adjustable. - Your microphone or camera is on. You're probably on a call, and it won't talk over one. - A Focus mode is on. It follows the Focus settings you already have on your Mac. - It's your quiet hours. You choose the hours on the settings page. - Your Mac isn't on your home network. It knows home by your router's hardware address. It never uses GPS or Location Services. - It spoke a moment ago, or has reached its hourly limit. A long session won't turn into a stream of alerts. If none of them is true, your Mac says the line. Volume: If your Mac is muted or turned down, Heads-up raises the volume for the alert and puts it back afterwards. It has hard limits that no setting can go past, and any output it doesn't recognise gets the headphone limit. - 50%: The most it will ever play through AirPods or headphones. - 90%: The most it will ever play through your Mac's speakers. ## More with your own voice key Everything above works without a key. Add an ElevenLabs or Sarvam key and Heads-up can record new lines for you. - It says which project is calling. “Hello from Brand Bakery Hub.” Handy when several sessions are running. Each name is recorded once and cached, up to 20 new names a day. - Claude can add a sentence of its own. For when the fixed line isn't enough: “The migration ran, but two tables need your review.” - You can rewrite any alert. Only the line you change gets recorded. - You get more voices. Any voice in your ElevenLabs account, or any of Sarvam's 37 speakers. You pay your provider directly, and the amounts are small. A project name is 16 to 25 characters, recorded once per voice. All 20 alerts in a new voice come to about 570 characters, and ElevenLabs' free plan includes 10,000 a month. A daily budget, 1,000 characters per provider unless you change it, caps anything recorded automatically. The key is stored in the macOS Keychain. It never goes into a file or a log, and the settings page never shows it back to you. Project names and Claude's own words stay off until the key checks out and you switch them on. - Get an ElevenLabs key: https://elevenlabs.io/app/settings/api-keys - Get a Sarvam key: https://dashboard.sarvam.ai ## What stays on your Mac All of it, unless you add a voice key. Heads-up is one small Node server and a Swift helper, with no npm dependencies. There's no account and no telemetry. With a key, the short line being recorded goes to your voice provider and nothing else does. Claude is told to keep code, file paths and secrets out of anything it says. ## What Claude calls The plugin adds one tool, notify_user, and a skill that tells Claude to call it once, at the end of a turn where you have to do something, and to leave it alone otherwise. Claude calls notify_user with a status (one of 20), an optional message (needs your key), repeat (1 to 3) and an optional volume, always under the caps. - Hooks announce permission prompts and turns longer than 2 minutes, even if Claude forgets to call the tool. Background sessions never set them off. - When a rule blocks an alert, the tool answers “Not played” with the reason, and Claude moves on without retrying. ## Add it to your agent Heads-up is a small MCP server with a skill and hooks. One command sets it up in Claude Code, and in Codex too if you use it. Requirements: macOS, Node.js 20 or later, and Claude Code or Codex. Xcode Command Line Tools for call detection. ffmpeg from Homebrew, only for lines recorded with your own key. 1. Install. In Terminal: npx headsup-mcp install The installer checks for Node and ffmpeg, builds the call detector, installs the plugin in Claude Code (and in Codex if it's there) and allows its tool so alerts don't wait on a permission prompt, clears out any older setup so nothing plays twice, and adds the headsup command. Add `--dry-run` to see the changes first. It's safe to run again after an update. In Codex, open `/hooks` once and trust its three hooks. Codex asks again after every update. Or inside Claude Code: /plugin install heads-up --marketplace abhishek207/headsup-mcp. Just the plugin. Call detection and the `headsup` command come with the Terminal install. 2. Hear it: headsup test review. Your Mac says "Hello. I need your review." 3. Ask your agent: "Tell me out loud when you're done." Add it to your next task, then step away. It stays quiet while you're using the keyboard or mouse. The headsup command: It comes with the Terminal install. - headsup: Opens the settings page. It runs on your Mac only, at 127.0.0.1:4777. - headsup status: Shows whether an alert would play right now, and what would stop it. - headsup mute 30: Quiet for half an hour. `headsup unmute` ends it early. - headsup say "The build is green.": Speaks a line of your own, with your voice key. - headsup uninstall: Takes it all out, and keeps your settings. Every command: https://github.com/abhishek207/headsup-mcp#use ## Questions ### Is it free? Yes, and it will stay free. There's no paid version. The built-in voices need no account or key. If you add your own ElevenLabs or Sarvam key, they bill you for what you record. The code is open source too, under the GNU GPL v3. ### Does it work on Windows or Linux? Not yet. It's Mac only for now. A Windows version is planned. ### Does it work with Codex, Cursor or other agents? Claude Code and Codex. The Terminal install adds it to Codex if Codex is on your Mac. Open /hooks there once and trust its three hooks, and again after each update. There's no package for Cursor or other agents yet. ### Will it talk over my meetings? No. It stays silent while your mic or camera is in use, while a Focus mode is on and during your quiet hours. It also skips alerts if you've touched the keyboard or mouse in the last minute, because then you're already there. ### Will it blast my AirPods? No. Headphones are capped at 50% and speakers at 90%, and no setting goes past that. If your Mac is muted, it turns up for the alert and then puts the volume back. ### Does anything leave my Mac? Only if you add a voice key. Then the short line being recorded, a project name or Claude's sentence, goes to your provider. There's no telemetry and no Heads-up account. Claude is told to keep code, paths and secrets out of spoken lines. ### Where is my API key stored? In the macOS Keychain. It's never written to a config file or a log, and the settings page never shows it back. ### How much will a key cost me? Very little. A project name is 16 to 25 characters, recorded once per voice. A daily budget caps automatic recording at 1,000 characters per provider by default, and ElevenLabs' free plan includes 10,000 characters a month. ### What if Claude forgets to call it? Hooks cover the cases that matter most: permission prompts, and any turn that runs longer than 2 minutes. ### Can I change what it says? Yes, with a key. Edit any alert's wording on the settings page, add voices from your ElevenLabs account or Sarvam's 37 speakers, or let Claude say a short line of its own. ### How do I turn it off? Run headsup off, or headsup mute 30 for half an hour. headsup uninstall removes it completely. ### Who made it? Brand Bakery, a founder-led studio in India. Voices made with ElevenLabs (elevenlabs.io). Powered by Sarvam. ## Credits Voices made with ElevenLabs (elevenlabs.io): Brian, Sarah, George, Alice and Charlie. Powered by Sarvam: Aditya and Priya, recorded with Sarvam Bulbul v3. Heads-up is free and will stay free. There is no paid version. It's an independent project, not affiliated with Anthropic, ElevenLabs or Sarvam. Open source on GitHub (https://github.com/abhishek207/headsup-mcp), under the GNU GPL v3. The built-in voice clips are not covered by it. --- Brand Bakery is a design-first digital studio in New Delhi. Start an enquiry at https://www.brandbakery.tech/contact or email support@brandbakery.tech. This is the Markdown copy of https://www.brandbakery.tech/products/heads-up; the site index for language models is https://www.brandbakery.tech/llms.txt.