Agent Status Sound

一个支持 Windows 和 macOS 的 Cursor 插件：主 Agent 完成工作或需要你接手时播放不同的提示音。

功能

• 主 Agent 正常完成一轮：播放上升三音。
• 主 Agent 报错结束：播放「需要你」的急促提示音。
• 主 Agent 主动提问：播放「需要你」提示音。
• Subagent 完成：静音。
• 用户主动中止：默认静音。
• 可选：Shell 或 MCP 工具开始前提醒。
• 无第三方 Python 依赖，首次运行自动生成 WAV。
• 内置 Cursor Skill，可让 Agent 帮你测试、配置和排错。

环境要求

• Windows 10/11 或 macOS
• Cursor
• Python 3

安装

Windows

在 PowerShell 中运行：

git clone https://github.com/wplf/agent-status-sound.git "$env:USERPROFILE\.cursor\plugins\local\agent-status-sound"
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.cursor\plugins\local\agent-status-sound\install.ps1"

macOS

在 Terminal 中运行：

git clone https://github.com/wplf/agent-status-sound.git ~/.cursor/plugins/local/agent-status-sound
sh ~/.cursor/plugins/local/agent-status-sound/install.sh

然后在 Cursor 中按 Ctrl+Shift+P，执行 Developer: Reload Window。

打开 Customize 应能看到 Agent Status Sound；打开 Cursor Settings → Hooks 应能看到 stop、preToolUse、 beforeShellExecution 和 beforeMCPExecution。

如果目标目录已存在，请先在该目录执行 git pull，再运行 install.ps1。

试听

py -3 "$env:USERPROFILE\.cursor\plugins\local\agent-status-sound\scripts\notify.py" --test all

macOS：

python3 ~/.cursor/plugins/local/agent-status-sound/scripts/notify.py --test all

也可以在 Agent 中运行 /test-status-sound。

配置

编辑插件根目录中的 config.json：

{
  "enabled": true,
  "notifyOnStop": true,
  "notifyOnAsk": true,
  "notifyOnError": true,
  "silentOnAbort": true,
  "notifyOnToolGate": false,
  "debounceMs": 1500,
  "volume": 0.32
}

将 notifyOnToolGate 设为 true，会在每次 Shell 或 MCP 工具调用前 播放「需要你」提示音。这是对权限等待的近似提醒，可能会比较频繁。

改动 volume 后，删除 assets/done.wav 和 assets/need-you.wav； 下次播放会按新音量重新生成。

已知限制

Cursor 当前没有独立的 PermissionRequest hook，因此插件无法准确判断 某个批准框是否真的在等待用户。它能可靠覆盖完成、错误和 Agent 主动提问； 工具调用前提醒是可选的近似方案。

插件没有注册 subagentStop，并会忽略带有 subagent_id、 subagent_type、parent_conversation_id、agent_id 或 is_subagent 标识的完成事件。部分 Cursor 版本不会在子 Agent 内部事件中提供父子关联字段； 这是 Cursor Hook API 当前的限制。

排错

• 没有声音：先运行上面的 --test all。
• 测试有声但 Agent 结束无声：查看 Output → Cursor Hooks。
• Hook 未出现：执行 Developer: Reload Window。
• 重复响铃：检查是否还配置了用户级 ~/.cursor/hooks.json；脚本也内置了 1.5 秒同类声音去重。

开发

项目结构：

.cursor-plugin/plugin.json    插件清单
hooks/hooks.json              Cursor hook 配置
scripts/notify.py             事件分类、声音生成与播放
scripts/notify                macOS Python 启动器
scripts/notify.cmd            Windows/macOS 共用 Hook 入口
skills/agent-status-sound/    Cursor Skill
commands/test-status-sound.md 测试命令
tests/test_notify.py           事件分类测试

License

MIT