Heads-up

Heads-up

当 Claude Code 在你的 Mac、Linux 或 Windows 电脑上完成任务或需要你时，为你播报提醒。这样你可以离开键盘，同时知道何时该回来。

“来自 Kosh 的问候。我需要你审核一下。”

Heads-up 是 Claude Code（和 Codex）的插件，包含一个小型本地 MCP 服务、一项教会 Agent 何时该发出提醒的技能，以及一些钩子。Agent 会调用一个工具 notify_user，你的电脑就会播放一段简短语音：可以是 20 段内置音频之一，也可以是 Claude 用你选定的声音说出自己的话。语音由运行在你电脑上的免费语音服务、ElevenLabs 或 Sarvam 提供，你需要使用自己的密钥。通话期间、开启专注模式或勿扰模式时，或者你不在家时，它会保持安静；它也可以等到你离开键盘后再提醒。

功能

• 20 条提醒，包含 7 种语音（美国、英国、澳大利亚和印度口音；男声和女声），内置 140 条音频片段。无需 API 密钥。
• 无需密钥即可使用：开箱即用，可播放内置音频片段（“Hello. I need your review.”）。项目名称和 Claude 自己的话语是可选功能，下载本地语音或添加自己的 ElevenLabs 或 Sarvam 密钥后即可启用。
• 本地语音（免费，可选）：语音模型可在你的电脑上朗读，无需密钥或账号，提供两种尺寸，下载前可试听。包含 12 种语音（美国、英国和印度英语），没有每日限制。参见本地语音。
• 项目名称（本地语音或你的密钥）：“Hello from Brand Bakery Hub.”每个项目的名称只录制一次，然后缓存。
• 告诉你哪个聊天需要你：开启多个会话时，提醒会以 Claude 应用中显示的聊天标题（或 Claude Code 中的 /rename 标题）开头：“Hello from Kosh. Thread: Fix Safari export button. I need your review.”始终支持本地语音；付费语音仅用于 Claude 自行撰写的内容。
• Claude 自己的话语（本地语音或你的密钥）：固定提醒内容不够充分时，Claude 会添加一段简短的 message（“The migration ran, but two tables need your review.”），并即时朗读。内容会经过清理（不含代码或链接）、限制长度并缓存。使用密钥时，也会计入每日字符数额度。如果无法录制，则播放常规提醒。
• 使用服务商提供的任意语音（你的密钥）：在设置页面添加 ElevenLabs 账号中的语音，或 Sarvam 的 37 种语音。每条提醒会在首次播放时录制，也可以一次性全部录制。
• 自定义提醒内容（本地语音或你的密钥）：在设置页面更改任意提醒的内容；只会录制该条内容。
• 费用一目了然：显示各服务商当天和当月使用的字符数，以及 ElevenLabs 套餐的额度计数器。
• 通过 Claude Code hooks 自动提醒：权限提示，以及运行时间超过 2 分钟的轮次，即使 Claude 忘记调用工具也会提醒。后台会话（claude -p、SDK workers）不会触发提醒。
• 默认不打扰
  • 离开检测（默认关闭）：如果你在过去 60 秒内使用过键盘或鼠标，则静音。此功能默认关闭，因为开启多个会话时，这个会话需要你处理时，你通常正在另一个会话中打字；可在设置中开启。
  • 通话和专注模式：正在使用麦克风或摄像头，或 macOS 专注模式或桌面的勿扰模式开启时，保持静音。如果提醒播放期间麦克风或摄像头开始工作（听写、通话），则立即停止。
  • 停止：运行 headsup stop，或点击设置页面上的“停止”按钮，即可在提醒说到一半时结束播放（并丢弃所有排队等待的提醒）。如果希望按一下键就能停止，可通过 macOS 快捷指令（或桌面的键盘快捷键）将 headsup stop 绑定到按键。
  • 地点：可选设置为仅在已保存的网络（家庭、办公室）上播放，通过路由器的硬件地址识别网络。无需 GPS。
  • 静音时段、提醒间隔和每小时提醒上限。
• 听力安全音量：如果电脑处于静音或音量较低状态，提醒会短暂调高音量，然后恢复原状。AirPods 和耳机的音量不会超过 50%；扬声器不会超过 90%。Heads-up 无法判断声音播放设备时，会采用耳机音量上限。
• 设置页面：http://127.0.0.1:4777（headsup），仅限本地访问。

要求

• Node.js 20+ 和 Claude Code（或 Codex），支持 macOS、Linux 或 Windows 10/11
• 录制任何内容都需要 ffmpeg，包括使用本地语音或你的密钥录制（brew install ffmpeg、sudo apt install ffmpeg、winget install Gyan.FFmpeg）
• 可选：本地语音（占用约 420 MB 磁盘空间，较小的模型占用约 210 MB），或 ElevenLabs 和/或 Sarvam API 密钥；仅在录制新内容时需要

平台

	macOS	Linux	Windows
声音	内置（afplay）	PipeWire 或 PulseAudio（pw-play、paplay），否则使用 ffplay	内置
安全音量	内置	pactl 或 wpctl	Windows 助手
通话（麦克风、摄像头）	通话检测器，使用 Xcode Command Line Tools（swiftc）构建	PipeWire（pw-dump）或 pactl；摄像头来自 /dev/video*	Windows 助手（读取 Windows 自带的麦克风和摄像头隐私记录）
专注 / 勿扰	专注模式，支持手动和计划设置	GNOME、KDE Plasma、Xfce、dunst、SwayNC、mako	勿扰（Windows 10 上为专注助手）
离开（空闲）	内置	GNOME，或 X11 上的 xprintidle	Windows 助手
密钥	Keychain	通过 secret-tool 使用密钥环（GNOME Keyring、KWallet）	凭据管理器，通过 Windows 助手使用

headsup install 会检查上述所有项目，并告知缺少哪些内容。在 Linux 上，它会打印适用于你所用发行版的安装命令（apt、dnf、pacman、zypper）；无需构建任何助手。在 Windows 上，它会使用 Windows 自带的 C# 编译器（.NET Framework 4）构建小型助手，因此无需额外下载。Heads-up 无法检测到的任何项目都会在设置页面和 headsup status 中报告，绝不会被当作“未在通话中”。

Linux 和 Windows 支持是从 1.7.0 版本开始新增的。Linux 已在使用 GNOME 勿扰功能的 PipeWire 上测试；其他桌面环境则尽力支持。Windows 支持仍处于早期阶段：尚未在真实 PC 上运行过，因此如果遇到问题，请提交 issue。通过 SSH、在容器中或在没有声音服务的机器上运行时，系统会说明原因并跳过提醒，而不是对着空处播放声音。

安装

在 Claude Code 中，只需一步：

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

或者在终端中运行，这也会构建系统所需的助手并添加 headsup 命令：

npx headsup-mcp install      # add --dry-run to see the changes first

从检出目录运行 npm run setup，也会使用本地副本执行相同操作。更新后可以安全地再次运行。它会：

1. 检查 Node 和 ffmpeg；在 Linux 上还会检查声音、通话和密钥环工具，
2. 将助手构建到数据文件夹中：macOS 上构建通话检测器（需要 swiftc），Windows 上构建 Windows 助手；Linux 无需助手，
3. 添加 Heads-up marketplace，并在 Claude Code 中安装插件；同时在 ~/.claude/settings.json 中允许其 notify_user 工具（备份文件为 settings.json.heads-up-backup）。如果没有允许规则，每个会话中的第一条提醒都会等待权限提示；你不在时，这就失去了提醒的意义，
4. 如果发现插件安装前的设置，则将其移除（MCP 条目、hooks、CLAUDE.md 部分），以免提醒重复，
5. 如果也安装了 Codex，则同时在 Codex 中安装插件；使用 /hooks 信任其中的 hooks（Heads-up 每次更新后，Codex 都会再次询问；在你信任之前，codex exec 会将这些 hooks 报告为 Failed），
6. 将 headsup 命令写入 ~/.local/bin（Windows 上为 %USERPROFILE%\.local\bin\headsup.cmd，与 Claude Code 自带安装程序使用的文件夹相同）。

headsup uninstall 会移除所有相关内容，同时保留你的设置。

插件包含的内容

部分	Claude Code	Codex
清单	.claude-plugin/plugin.json（内联 MCP 服务）	.codex-plugin/plugin.json
MCP 服务 heads-up	server.mjs	.codex-plugin/mcp.json 中的 server.mjs
Skill	skills/heads-up/SKILL.md	相同
Hooks	hooks/hooks.json：prompt、notification、stop	hooks/codex.json：prompt、permission request、stop
Marketplace	.claude-plugin/marketplace.json	同一文件（Codex 会读取）

使用 npm run validate 检查清单。

其他 MCP 客户端

任何 MCP 客户端都可以通过 stdio 独立运行此服务：

npx -y headsup-mcp serve

这样客户端就能使用 notify_user 工具。Skill 和 hooks 仅随 Claude Code 插件提供，而 npx headsup-mcp install 会构建助手。

使用

headsup              # open the settings page
headsup status       # what would happen right now
headsup test review  # play an alert now
headsup stop         # stop the alert that's speaking
headsup mute 30      # mute for 30 minutes; headsup unmute
headsup off          # master switch; headsup on
headsup say "The build is green."   # hear a line of your own (local voice or your key)
headsup usage        # characters sent to your voice providers
headsup local install   # download the free local voice (full, or: headsup local install small); headsup local remove

给 Agent 的说明

设置页面有一个文本框，你可以在其中告诉 Agent 何时提醒你以及要说什么，例如“先说你需要我做什么，然后再说任务名称”或“用时不到 5 分钟的任务不用提醒我”。Heads-up 会将这段文字保存在单独的配置中，并在每次会话开始时通过 MCP 服务的说明和 notify_user 工具描述将其提供给每个 Agent。它不会写入你的 CLAUDE.md 或技能文件，因此插件更新永远不会将其覆盖。已打开的会话在重启后会应用更改。仍由你的开关、静音时段和音量上限决定播放内容。

本地语音

这是一种在电脑上运行的免费语音，适合想要听到项目名称和 Claude 原声、又不想付费购买密钥的用户。下载前它处于关闭状态。在设置页面的“本地语音”下，播放每个模型和 12 种语音的示例，下载你喜欢的模型，然后在“语音”下选择该模型的 12 种语音之一：“这台 Mac 上”（Linux 上为“这台电脑上”，Windows 上为“这台 PC 上”）。它可在 macOS（Apple 芯片和 Intel）、Linux（x64 和 arm64）及 Windows（x64；尚未在真实 PC 上测试）上运行。在终端中运行：headsup local install（完整质量）或 headsup local install small。

模型	音质	下载大小	磁盘占用	每条新语音（M4 MacBook Air）
完整质量（推荐）	清晰自然	约 360 MB	约 420 MB	约 4 秒，占用 730 MB 内存
较小模型	略显粗糙、带有嗡嗡声，速度约慢一半	约 140 MB	约 210 MB	约 7 秒，占用 500 MB 内存

• 模型介绍： Kokoro，一个拥有 8200 万参数的文本转语音模型，由 sherpa-onnx 运行。较小的模型是同一模型的 8 位版本，因此音质略显粗糙。Heads-up 会从官方发布源下载模型，使用固定的校验和检查每个文件，并将其保存在数据文件夹中。它不会安装到其他位置。
• 一次使用一个模型： 切换模型时会下载另一个模型（保留引擎）并替换当前模型；在新模型准备就绪前，当前模型仍可正常使用。已用本地语音录制的语句会使用新模型重新生成。
• 费用： 每条语句均免费。没有每日额度，也不会限制新项目名称的数量。每次录制新语句时，模型会占用 CPU 和内存几秒钟，然后释放资源；下载完成后，设置页面会显示模型在你的电脑上占用的资源。提醒之间不会保持加载状态，已生成的语句会缓存并可即时播放。
• 语速和长度： 在“本地语音”下，“语速”可设置说话速度（0.7× 至 1.5×），“最长语句”可设置 Claude 在每次提醒中能说多少内容（默认 1,000 个字符，最多 2,000 个字符）。由于它是免费的，Claude 会被要求说出所需的全部内容：发生了什么、涉及哪项审核、决定或输入，以及可选方案。长语句会在第一句话准备好后开始播放，其余部分会在播放过程中生成。付费语音会在“Claude 原声”下保留各自较短的限制。
• 语音： 6 种美式英语、4 种英式英语、2 种印度语音（用印地语语音朗读英语）。如需母语级的印度英语语音，请使用 Sarvam 和你的密钥。
• 密钥仍可使用： 本地语音是 ElevenLabs 和 Sarvam 之外的另一种选择。如果你不想在电脑上运行模型，可以跳过它并使用密钥。
• headsup local remove 会将其删除。如果你没有密钥，项目名称和 Claude 原声会再次关闭。

API 密钥

只有在使用 ElevenLabs 或 Sarvam 录制新内容时才需要：项目名称、你撰写的内容、新增的声音以及 Claude 自己的话。本地声音无需密钥。在设置页面添加密钥；密钥会存入系统的密钥库（macOS Keychain、Linux 密钥环、Windows Credential Manager），不会写入文件，也不会再次显示。ElevenLabs 密钥会在保存前进行检查（免费），「测试」按钮会用你的密钥朗读几个词。Heads-up 也会从环境变量 ELEVENLABS_API_KEY / SARVAM_API_KEY 以及名为 elevenlabs-api-key / sarvam-api-key 的 Keychain 项目中读取密钥。

使用密钥后，Claude 的内容会发送给你的服务商进行语音合成，因此系统会要求 Claude 不要在内容中包含代码、路径和机密信息；Heads-up 也会在发送前，将任何漏网的链接、文件路径、电子邮件地址和类似密钥的字符串替换为「一个链接」「一个文件」等内容。每日预算（默认为 1,000 个字符）会限制所有自动录制的内容；你在设置页面录制的内容不受限制。

文件存放位置

• 插件文件夹（Claude Code 将其保存在 ~/.claude/plugins/ 下）：代码和内置声音。
• 数据文件夹（或 $HEADS_UP_HOME）：macOS 上为 ~/Library/Application Support/heads-up，Linux 上为 ~/.local/share/heads-up（如果设置了 $XDG_DATA_HOME/heads-up，则使用该路径），Windows 上为 %LOCALAPPDATA%\heads-up。其中包含你的设置、提醒日志、钩子状态、录音（segments/、cache/clips/）、用量日志（usage.json），以及你下载的本地声音（local/）。

隐私与安全

• 哪些内容会离开你的电脑： 在添加密钥之前，不会有任何内容离开你的电脑。本地声音会在你的电脑上合成语音；下载它会从 npm 和 GitHub 获取两个文件，不会发送任何关于你的信息。使用密钥后，只有正在录制的文本（项目名称、你撰写的内容、Claude 的话）会发送给 ElevenLabs 或 Sarvam，此外还会免费调用接口来列出你的 ElevenLabs 声音和套餐用量。没有分析、没有遥测，也不会连接其他服务。
• 哪些内容会留在你的电脑上： 通话、专注状态、离开状态和位置检查都在本地运行。麦克风和摄像头检查只会询问系统设备是否正在使用（macOS、PipeWire 或 Windows 的隐私记录）；它不会打开设备或录制任何内容。位置信息是路由器的硬件地址，保存在你的设置文件中。提醒日志（包括 Claude 的话）保存在上方的数据文件夹中，只有你能读取。
• 密钥： 保存在系统的密钥库中（或你的环境变量中），绝不会写入文件、日志或设置页面。headsup uninstall 会保留密钥，以便你重新安装，并打印删除密钥的命令。
• 设置页面： 仅监听 127.0.0.1，只响应 127.0.0.1 和 localhost（不会受到 DNS 重绑定攻击），拒绝来自其他网站的请求，无法被其他网站嵌入，并会在空闲 30 分钟后停止。
• 无依赖项： 使用纯 Node 和系统自带工具。运行时唯一会获取的内容是本地声音，而且只有在你主动请求时才会获取：固定版本的 sherpa-onnx 构建和 Kokoro 模型，使用前都会分别通过 SHA 校验和检查。
• 发现安全问题？请参阅 SECURITY.md。

故障排除

• 数据文件夹中的 hook.log 会逐行记录每次钩子决策及其原因。
• 设置页面的“近期提醒”会显示每条提醒，无论是已播放还是已跳过，并附上原因。
• HEADS_UP_DISABLED=1 可让单个进程静音所有声音（适用于测试）。
• “此设备没有声音输出”表示 Heads-up 未检测到声音服务器（例如 SSH 会话、容器、未安装 PipeWire 或 PulseAudio 的 Linux 设备）。如果你能通过其他方式听到声音，请设置 HEADS_UP_ASSUME_AUDIO=1。
• Linux：headsup status 会指出哪些检测器无法获取桌面上的信息（例如某些桌面环境中的“请勿打扰”状态、KDE Wayland 上的空闲时间）；这些检查在相应环境中会被直接跳过。
• Codex 不会告知钩子某个会话是否为交互式会话，因此长时间运行的 codex exec 也会在完成时发出提醒。Claude Code 的后台运行（claude -p、SDK）会被忽略。
• Codex 在全自动（“YOLO”）模式下不会请求批准，因此不会触发批准提醒。

声音和鸣谢

声音由 ElevenLabs（elevenlabs.io）和 Sarvam AI 提供。

• 英语音频片段：使用 ElevenLabs 免费方案制作，采用 Brian、Sarah、George、Alice 和 Charlie 的声音。鸣谢：elevenlabs.io。仅限非商业用途。
• 印度英语音频片段：使用 Sarvam Bulbul v3 的 Aditya 和 Priya 声音。
• 本地语音：Kokoro-82M 由 hexgrad 提供（Apache-2.0），通过 sherpa-onnx（Apache-2.0）运行；该工具使用 espeak-ng（GPL-3.0）进行发音处理。按需下载，不随此软件包一同提供。

使用你自己的密钥录制的语音，归属于你自己的账户，并受你所用服务提供商的条款约束。

参与贡献

使用它、派生它、修改它。不接受外部拉取请求，并会自动关闭；欢迎通过问题报告 Bug。请参阅 CONTRIBUTING.md。

许可证

版权所有 (C) 2026 Brand Bakery。

代码依据 GNU 通用公共许可证第 3 版（GPL-3.0-only）授权：你可以自由使用、修改和分享；如果分发修改后的版本，必须继续采用 GPL 授权并提供源代码。voices/ 中内置的音频片段不受该许可证约束；请参阅 voices/NOTICE.md。

---

由 Brand Bakery 构建并维护。