Heads-up
Spoken alerts when Claude Code or Codex finishes a task or needs your review
- Pricing
- Free
- Platforms
- macOS, Linux, Windows
- Runs
- Locally
- Version
- 1.7.0
- Listing updated
- 3 days ago
About Heads-up
Heads-up is a free MCP server for developer tools. It runs locally on your machine and is started by your AI client.
Heads-up lets you step away from the keyboard and still know when a coding agent wants you back. The agent calls one tool, notify_user, and the computer plays a short spoken line, such as "Hello from Kosh. I need your review." It ships as a plugin for Claude Code and Codex made of a local MCP server, a skill that teaches the agent when to speak up, and hooks.
Out of the box it plays one of 20 built-in alerts, with 140 clips across 7 voices (American, British, Australian and Indian English), and needs no API key. An optional free local voice model, or your own ElevenLabs or Sarvam key, adds project names, the chat title when several sessions are open, and short messages written by Claude itself, which are cleaned of code and links and capped in length.
It tries to be polite. Alerts stay silent while a microphone or camera is in use or macOS Focus or Do Not Disturb is on, and can be limited to saved networks, quiet hours and an hourly cap. Hooks fire automatically on permission prompts and on turns that run longer than 2 minutes. A stop command or settings-page button cuts an alert off mid-sentence, and volume is briefly raised if the machine is muted, with headphones kept at or below 50%.
Install
Run in a terminal
claude mcp add headsup-mcp -- npx -y headsup-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"headsup-mcp": {
"command": "npx",
"args": [
"-y",
"headsup-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"headsup-mcp": {
"command": "npx",
"args": [
"-y",
"headsup-mcp"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"headsup-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"headsup-mcp"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"headsup-mcp": {
"command": "npx",
"args": [
"-y",
"headsup-mcp"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"headsup-mcp": {
"command": "npx",
"args": [
"-y",
"headsup-mcp"
]
}
}
}Tools this server provides (1)
Taken from the project documentation; the running server may differ.
- notify_user
- Plays a short spoken alert, optionally with a message written by the agent.
What it does
- One notify tool
- The agent calls notify_user to speak a short alert instead of you watching the terminal.
- Built-in clips
- 20 alerts in 7 voices play without any key or account.
- Local or paid voices
- A free on-device voice, or your own ElevenLabs or Sarvam key, adds project names and Claude's own wording.
- Automatic hooks
- Permission prompts and turns longer than 2 minutes trigger an alert even if the agent forgets.
- Quiet when needed
- Silent during calls, Focus or Do Not Disturb, with optional away detection, quiet hours and hourly limits.
- Usage visibility
- The settings page shows characters used per provider today and this month.
- Instant stop
- headsup stop or a button on the settings page ends an alert mid-sentence.
Good for
- Get a spoken cue when a long Claude Code run finishes
- Hear which of several open sessions needs a permission decision
- Hear a short status such as a migration result without checking the screen
- Keep alerts off during calls and focus time
- Customise what each alert says in your own wording
Pricing
Free
Free; ElevenLabs or Sarvam voices use your own key and plan
Prices change. Check brandbakery.tech before you buy.
Heads-up FAQ
Does it need an API key?
No. The 20 built-in alerts play without one. Project names and Claude's own words need the free local voice or an ElevenLabs or Sarvam key.
Which systems does it run on?
Mac, Linux and Windows, according to the registry entry and README.
Will it interrupt me on calls?
No. It stays silent while a microphone or camera is in use or while Focus or Do Not Disturb is on.
How do I silence an alert already playing?
Run headsup stop, or press Stop on the settings page.
Is Heads-up free?
Yes. Heads-up is free to use.
How do I add Heads-up to Claude Code?
Run this command in your terminal: claude mcp add headsup-mcp -- npx -y headsup-mcp
What are the best alternatives to Heads-up?
The closest alternatives to Heads-up are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.
Alternatives to Heads-up

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

GitHub
MCP serverOfficial MCP server connecting AI assistants to GitHub repos, issues and workflows
Not checked yet- Remote
- Open source
- 34.5K GitHub stars
- Developer tools

Serena MCP: the IDE for your agent
MCP serverMCP toolkit giving coding agents symbol-level code retrieval and editing
Runs locally- Open source
- 31.5K GitHub stars
- Developer tools

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Ha MCP
MCP serverMCP server for managing and automating Home Assistant from AI assistants
Runs locally- 8 tools
- Open source
- 7.9K GitHub stars
- Productivity