Start a project

Heads-upby Brand Bakery

Claude needs you. Now you'll hear it.

A small, free Mac plugin that speaks up when Claude Code finishes a task, needs your review or hits a wall. Quiet when you're busy. Gentle on your ears.

  • Free
  • macOS
  • Works with Claude Code

Voices made with ElevenLabs (elevenlabs.io) · Powered by Sarvam

Open source under MIT at launch.

“Hello from Brand Bakery Hub. I need your review.”With a project name

Install for Claude Code

How it works

Hear it from the kitchen.

  1. 1

    Claude stops.

    It finished, needs a review, or hit an error.

  2. 2

    Heads-up checks the room.

    Are you typing? On a call? In Focus? At home? Did it speak a moment ago?

  3. 3

    Your Mac speaks.

    "Hello from your project. I need your review." Volume comes up just enough, then goes back.

Listen

Seven voices. One line.

Every voice says the same thing, so the voice is the only difference. Each clip starts with "Hello." and a short pause.

  • BrianAmerican male, default

    “Hello. I need your review.”

  • SarahAmerican female

    “Hello. I need your review.”

  • GeorgeBritish male

    “Hello. I need your review.”

  • AliceBritish female

    “Hello. I need your review.”

  • CharlieAustralian male

    “Hello. I need your review.”

  • AdityaIndian male

    “Hello. I need your review.”

  • PriyaIndian female

    “Hello. I need your review.”

Different alerts, default voice

  • Task completeBrian

    “Hello. I've completed the task.”

  • ApprovalBrian

    “Hello. I need your approval to continue.”

  • StuckBrian

    “Hello. I'm stuck, and I need your help.”

  • Tests passedBrian

    “Hello. All the tests are passing.”

  • Deploy failedBrian

    “Hello. The deployment failed.”

  • Long task startedBrian

    “Hello. This will take a while. I'll let you know when it's done.”

Voices made with ElevenLabs (elevenlabs.io) · Powered by Sarvam

Features

It knows when to stay quiet.

Twelve things it does, out of the box. The ones marked with a key need your own ElevenLabs or Sarvam key.

  • 20 alerts

    Done, review, approval, question, stuck, error, tests passed or failed, deployed, PR ready, usage limit and more.

  • 7 voices

    American, British, Australian and Indian accents, male and female. Built in, no key needed.

  • Project namesNeeds your own voice key

    "Hello from Brand Bakery Hub." Know which session is calling.

  • Claude's own wordsNeeds your own voice key

    When a fixed line isn't enough, Claude adds a short sentence and it's spoken in your voice.

  • Stays quiet

    Skips alerts while you're at the keyboard, on a call, in Focus, during quiet hours, or away from home.

  • Ear-safe volume

    Raises a muted Mac for the alert only, then restores it. Hard caps: 50% on headphones, 90% on speakers.

  • Automatic alerts

    Hooks announce permission prompts and long turns even if Claude doesn't call the tool. Background sessions never trigger them.

  • Settings page

    A local page to pick voices, switch alerts on and off, edit wording, set limits and see usage.

  • Your wordingNeeds your own voice key

    Change what any alert says. Only that line is recorded.

  • Cost you can see

    Characters used today and this month, plus a daily budget so automatic recording never runs away.

  • Private by design

    Runs on your Mac. No account, no telemetry. Keys live in the macOS Keychain and never touch a file.

  • One-command setup

    Install as a Claude Code plugin, or with one terminal command. Uninstall the same way.

Install for Claude CodeGitHub repo opens at launch

For the technical reader

One tool. Twenty lines.

This is what Claude actually calls. Press play on any row to hear it.

notify_user {
  status:  "review",  // one of 20
  message: "The migration ran, but two tables need your review.",
                      // optional, needs your key
  repeat:  1,         // 1 to 3
  volume:  65         // optional, under the safety caps
}
  • Skill included. The plugin ships a skill that teaches Claude when to call notify_user (once, at the end of a turn where you have to act) and when not to.
  • Hooks included. Prompt start, permission prompts and long turns.
  • Skipped is not an error. If a guardrail blocks an alert, the tool tells Claude "Not played: <reason>" and Claude doesn't retry.
The 20 statuses and what each one says, after "Hello."
StatusSpoken linePlay
Needs you
reviewI need your review.
feedbackI need your feedback.
inputI need your input.
approvalI need your approval to continue.
questionI have a quick question for you.
blockedI'm stuck, and I need your help.
sign_inI need you to sign in.
reminderI'm still waiting on you.
Finished
completedI've completed the task.
tests_passedAll the tests are passing.
deployedThe deployment is live.
pr_readyThe pull request is ready.
next_taskI'm ready for the next task.
Problems
errorSomething went wrong. Please take a look.
tests_failedSome tests are failing.
deploy_failedThe deployment failed.
limit_warningI'm close to my usage limit.
limit_reachedI've hit my usage limit.
Updates
long_taskThis will take a while. I'll let you know when it's done.
progressQuick update. I'm still working on it.

Every line starts with "Hello." (or "Hello from <project>.") and a short pause.

Settings page

Everything on one local page.

Run headsup and it opens at 127.0.0.1:4777. Captured on a Mac from the current build, with demo data. The page follows your Mac's light or dark mode, and so do these pictures.

The Heads-up settings page on a Mac: the status panel says Ready, with a waveform of "I've completed the task." in the American male voice, beside the Voice section with seven voices and the start of the Alerts list.
The settings page
The Alerts list on the settings page: the Needs you group with Review, Feedback, Input needed, Approval, Question and Stuck, each with edit, play and an on switch.
Switch alerts on and off
The Project names section: Say the project name is on, with BB Studio and Brand Bakery Hub listed, each saying "Hello from" its name.
Project names
The Claude's own words section: a switch to let Claude speak its own lines, a longest line of 160 characters, a daily budget of 1,000 characters, a faster model switch and a box to try a line.
Claude's own words
The Calls and Focus section: switches to stay silent while a microphone or camera is in use and while a Focus mode is on.
Quiet on calls and in Focus
The Limits section: speak only when you have been away for 60 seconds, quiet hours, a gap between alerts, an hourly limit and a chime before the voice.
Limits
The Volume section: alert volume and max for Mac speakers (hard limit 90%) and for AirPods and headphones (hard limit 50%).
Ear-safe volume
The Voice provider keys section: ElevenLabs and Sarvam rows, each using a key saved in the macOS Keychain, with Replace key, Save and Test. No key is shown.
Voice provider keys
Terminal output of headsup status: alerts active, away after 60 seconds, hooks on, voice american-male, live lines on, keys from the Keychain, location Home, no calls, no Focus.
headsup status in Terminal
The Heads-up status panel on a phone: Ready, a waveform of a spoken alert, Play test and Turn off, mute options, and recent alerts tagged Brand Bakery Hub and BB Studio, one skipped because you were at the keyboard.
On a phone-width window

Bring your own key

Your key, your words, your voice. Or no key at all.

A key is an optional upgrade. Everything in the first column works without one.

Without a key

  • The 140 built-in clips
  • All 20 alerts in all 7 voices
  • Every guardrail and volume feature

With your ElevenLabs or Sarvam key

  • Project names ("Hello from Brand Bakery Hub.")
  • Claude's own words for an alert
  • Your own wording for any alert
  • Any voice from your ElevenLabs account, or any of Sarvam's 37 speakers

Get an ElevenLabs keyGet a Sarvam key

  • Project names and Claude's own words stay off until you add a key and it's verified. You turn them on.
  • The key goes into your macOS Keychain. Heads-up never writes it to a file, a log or the page.
  • You pay your provider directly, and usage is small: a project name is about 16 to 25 characters, once per voice. All 20 alerts in a new voice is about 570 characters. ElevenLabs' free plan includes 10,000 characters a month.
  • A daily budget (1,000 characters per provider by default) caps everything recorded automatically.
  • Each project's name is recorded once and cached, so the next alert is instant. Up to 20 new names a day.

Privacy and safety

Nothing leaves your Mac unless you say so.

  • On your Mac.

    No account, no server, no telemetry. The only thing that leaves your Mac is text you send to your own voice provider.

  • Your ears.

    Volume caps no setting can override. Unknown output devices get the headphone limits.

  • Your attention.

    A gap between alerts, an hourly limit, quiet hours, and mute for 15 minutes to 4 hours.

Home is recognised by your router's hardware address, not GPS or Location Services.

Install

One command to install. One to remove.

Run this inside Claude Code.

/plugin install heads-up --marketplace abhishek207/headsup-mcp

Works once the GitHub repo is public, at launch.

What the installer does

  • Checks Node and ffmpeg
  • Builds the call detector
  • Installs the plugin and allows its tool, so alerts don't wait on a permission prompt
  • Removes any older setup, so alerts don't double
  • Adds the headsup command

Then

headsup
opens the settings page
headsup test review
plays an alert now
headsup uninstall
removes everything and keeps your settings

Requirements

  • macOS
  • Node.js 20+
  • Claude Code
  • Xcode Command Line Tools, for call detection
  • ffmpeg (Homebrew), only for lines recorded with your key

The README goes public with the repo.

Questions

Asked and answered.

Is it free?

Yes, completely, and it stays that way. There's no paid tier. The 140 built-in clips need no account or key. Features that record new audio use your own ElevenLabs or Sarvam key, billed by them to you.

Does it work on Windows or Linux?

Not yet. It's macOS only for now. A Windows version is planned.

Does it work with Codex, Cursor or other agents?

It's built for Claude Code. A Codex version is packaged but still being tested. Any MCP client can call notify_user, but the automatic hooks are Claude Code's.

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 quiet hours. It also skips alerts if you've touched the keyboard or mouse in the last minute, because you're already there.

Will it blast my AirPods?

No. Headphones are capped at 50% and speakers at 90%, and no setting can go past that. If your Mac is muted it turns up just for the alert, 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. No telemetry, 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 log, and the settings page never shows it back.

How much does a key cost me to use?

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. ElevenLabs' free plan includes 10,000 characters a month.

What if Claude forgets to call it?

Hooks cover the important cases: 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?

headsup off, or headsup mute 30 for half an hour. headsup uninstall removes it completely.

Who made it?

Brand Bakery. Voices made with ElevenLabs (elevenlabs.io). Powered by Sarvam.

Free, and it says hello.

Install Heads-up

/plugin install heads-up --marketplace abhishek207/headsup-mcp

Works once the GitHub repo is public, at launch.

GitHub repo opens at launch

Credits

Voices made with ElevenLabs (elevenlabs.io): Brian, Sarah, George, Alice and Charlie.

Powered by Sarvam: Aditya and Priya, recorded with Sarvam Bulbul v3.

Free, for everyone, for good. No paid tier, no pro version.

Heads-up is an independent project. Not affiliated with Anthropic, ElevenLabs or Sarvam.

Open source on GitHub under the MIT license, at launch.

Voices made with ElevenLabs (elevenlabs.io) · Powered by Sarvam

WhatsApp