peon-ping

• 安装
• 你会听到什么
• 快速控制
• 配置
• Peon 训练师
• MCP 服务器
• 多 IDE 支持
• 远程开发
• 移动通知
• 音效包
• 调试
• 卸载
• 要求
• 工作原理
• 链接

安装

方法 1：Homebrew（推荐）

brew install PeonPing/tap/peon-ping

然后运行 peon-ping-setup 注册钩子并下载音效包。适用于 macOS 和 Linux。

方法 2：安装脚本（macOS、Linux、WSL2）

curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash

⚠️ 在 WSL2 中，必须安装 ffmpeg 才能使用非 WAV 格式的音效包。在 Debian 发行版中，请使用以下命令安装：

sudo apt update; sudo apt install -y ffmpeg

方法 3：Windows 安装程序

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.ps1" -UseBasicParsing | Invoke-Expression

默认安装 5 个精选包（《魔兽争霸》、《星际争霸》、《传送门》）。再次运行可更新，同时保留配置和状态。或者 在 peonping.com 上交互式选择音效包，获取自定义安装命令。

有用的安装标志：

• --all — 安装所有可用的音效包
• --packs=peon,sc_kerrigan,... — 只安装特定的音效包
• --local — 将音效包、配置和钩子安装到当前项目的 ./.claude/ 目录下
• --global — 显式全局安装（与默认设置相同）
• --init-local-config — 仅创建 ./.claude/hooks/peon-ping/config.json

--local 不会修改你的 shell 配置文件（不会注入全局 peon 别名或补全功能）。钩子会以绝对路径注册在项目级别的 ./.claude/settings.json 中，因此无论你在项目中的哪个工作目录，它们都能正常工作。

示例：

curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash -s -- --all
curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash -s -- --packs=peon,sc_kerrigan
curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash -s -- --local

如果已经存在全局安装而你尝试进行本地安装（或反之），安装程序会提示你先移除现有的安装，以免发生冲突。

方法 4：先克隆并检查

git clone https://github.com/PeonPing/peon-ping.git
cd peon-ping
./install.sh

方法 5：Nix（macOS、Linux）

无需安装即可直接从源代码运行：

nix run github:PeonPing/peon-ping -- status
nix run github:PeonPing/peon-ping -- packs install peon

或者将其安装到你的用户配置文件中：

nix profile install github:PeonPing/peon-ping

开发环境（bats、shellcheck、nodejs）：

nix develop  # 或使用 direnv

Home Manager 模块（声明式配置）

对于可重复的配置，可以使用 Home Manager 模块：

# 在你的 home.nix 或 flake.nix 中
{ inputs, pkgs, ... }:

let
  peonCursorAdapterPath = "${inputs.peon-ping.packages.${pkgs.system}.default}/share/peon-ping/adapters/cursor.sh";
in {
  imports = [ inputs.peon-ping.homeManagerModules.default ];

  programs.peon-ping = {
    enable = true;
    package = inputs.peon-ping.packages.${pkgs.system}.default;

    settings = {
      default_pack = "glados";
      volume = 0.7;
      enabled = true;
      desktop_notifications = true;
      categories = {
        "session.start" = true;
        "task.complete" = true;
        "task.error" = true;
        "input.required" = true;
        "resource.limit" = true;
        "user.spam" = true;
      };
    };

    # 从 og-packs（简单字符串表示法）和自定义源（包含 name + src 的 attrset）安装音效包
    installPacks = [
      "peon"
      "glados"
      "sc_kerrigan"
      # 来自 GitHub 的自定义音效包（openpeon.com 注册表）
      {
        name = "mr_meeseeks";
        src = pkgs.fetchFromGitHub {
          owner = "kasperhendriks";
          repo = "openpeon-mrmeeseeks";
          rev = "main";  # 或使用提交哈希以确保可重复性
          sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
        };
      }
    ];
    enableZshIntegration = true;
  };

  # 光标钩子
  home.file.".cursor/hooks.json".text = builtins.toJSON {
    version = 1;
    hooks = {
      afterAgentResponse = [{ command = "bash ${peonCursorAdapterPath} afterAgentResponse"; }];
      stop               = [{ command = "bash ${peonCursorAdapterPath} stop"; }];
    };
  };
}

音效包安装：installPacks 选项支持两种格式：

• 简单字符串（例如 "peon"、"glados"）——从 og-packs 仓库获取
• 自定义源——一个包含 name 和 src 字段的 attrset，其中 src 可以是任何 Nix 获取器的结果（例如 pkgs.fetchFromGitHub）

对于在 openpeon.com 上列出的音效包，请找到其 GitHub 仓库链接，并使用 pkgs.fetchFromGitHub：

{
  name = "pack_name";
  src = pkgs.fetchFromGitHub {
    owner = "github-owner";
    repo = "repo-name";
    rev = "main";  # 或者使用具体的提交哈希或标签
    sha256 = "";   # 初次留空，Nix 会提示正确的哈希值
  };
}

IDE 钩子：peon-ping Home Manager 模块不会自动设置你的 IDE 钩子，以避免更新冲突。你需要根据自己的 IDE 配置方式自行定义这些钩子（见上文示例）。

• peon-ping 提供了适用于多种 IDE 的适配脚本，例如 cursor.sh — 参见 adapters/
• 你需要在钩子中调用这些脚本，例如：

  ${inputs.peon-ping.packages.${pkgs.system}.default}/share/peon-ping/adapters/$YOUR_IDE.sh EVENT_NAME
  

  如上文光标示例所示。

你会听到的内容

此外，在每个屏幕（macOS/WSL/MSYS2）上还会显示大型覆盖式横幅通知，并在终端标签页标题中显示 ● 项目：已完成——即使你在其他应用中，也能立即知道发生了什么。

peon-ping 实现了 Coding Event Sound Pack Specification (CESP)——一种开放标准，用于编码事件音效，任何智能型 IDE 都可以采用。

快速控制

在会议或配对会话期间需要静音声音和通知吗？有两种方法：

其他 CLI 命令：

peon pause                # 静音
peon resume               # 取消静音
peon mute                 # “pause”的别名
peon unmute               # “resume”的别名
peon status               # 检查是否已暂停或启用（简洁）
peon status --verbose     # 显示完整详情（通知、耳机、IDE 等）
peon volume               # 显示当前音量
peon volume 0.7           # 设置音量（0.0–1.0）
peon rotation             # 显示当前轮换模式
peon rotation random      # 设置轮换模式（随机|轮循|会话覆盖）
peon packs list           # 列出已安装的声音包
peon packs list --registry # 浏览注册表中所有可用包
peon packs community      # 列出按信任等级分组的所有注册表包（Windows）
peon packs search <query> # 按名称搜索注册表包（Windows）
peon packs install <p1,p2> # 从注册表安装包
peon packs install --all  # 安装注册表中的所有包
peon packs install-local <path> # 从本地目录安装包
peon packs use <name>     # 切换到特定包（在 Windows 上会自动从注册表安装）
peon packs use --install <name>  # 切换到指定包，必要时从注册表安装
peon packs next           # 循环切换到下一个包
peon packs remove <p1,p2> # 移除特定包
peon packs bind <name>    # 将包绑定到当前目录
peon packs bind --pattern <path> # 将包绑定到目录模式，例如 "*/services"
peon packs unbind         # 移除当前目录的绑定
peon packs bindings       # 列出所有已分配的绑定
peon notifications on     # 启用桌面通知
peon notifications off    # 禁用桌面通知
peon notifications overlay   # 使用大型叠加横幅（默认）
peon notifications standard  # 使用标准系统通知
peon notifications test      # 发送测试通知
peon notifications position [pos]    # 获取/设置通知位置（左上、中上、右上、左下、中下、右下）
peon notifications dismiss [N]       # 获取/设置自动关闭时间（秒）（0 = 持续显示）
peon notifications label [text|reset] # 获取/设置通知的项目标签覆盖
peon notifications template [key] [fmt]  # 获取/设置/重置消息模板（键：停止、权限、错误、空闲、提问）
peon preview              # 播放 session.start 中的所有声音
peon preview <category>   # 播放特定类别中的所有声音
peon preview --list       # 列出活动包中的所有类别
peon mobile ntfy <topic>  # 设置手机通知（免费）
peon mobile off           # 禁用手机通知
peon mobile test          # 发送测试通知
peon debug on             # 启用调试日志
peon debug off            # 禁用调试日志
peon debug status         # 显示调试状态、日志目录、文件数量及总大小
peon logs                 # 显示今日日志的最后 50 行
peon logs --last N        # 显示所有日志文件中的最后 N 行
peon logs --session ID    # 按会话 ID 过滤今日日志
peon logs --session ID --all  # 在所有日志文件中搜索会话 ID
peon logs --clear         # 删除所有日志文件（需确认）
peon relay --daemon       # 启动音频中继（用于 SSH/devcontainer）
peon relay --stop         # 停止后台中继

peon preview 可用的 CESP 类别：session.start、task.acknowledge、task.complete、task.error、input.required、resource.limit、user.spam。 （扩展类别 session.end 和 task.progress 已在 CESP 规范中定义，并由包清单支持，但目前尚未由内置钩子事件触发。）

支持选项卡补全——输入 peon packs use <TAB> 即可查看可用包名。

暂停会立即静音声音和桌面通知。暂停状态会持续到您恢复为止。暂停时标签页标题仍保持活跃。

配置

peon-ping 会在 Claude Code 中安装以下斜杠命令：

• /peon-ping-toggle — 静音/取消静音声音
• /peon-ping-config — 更改任何设置（音量、包、类别等）
• /peon-ping-rename <name> — 为当前会话命名，该名称将显示在通知标题和终端标签页标题中（零令牌，被钩子拦截）；不提供参数则恢复为自动检测

您也可以直接让 Claude 为您更改设置——例如“启用轮循包轮换”、“将音量设为 0.3”或“将 glados 添加到我的包轮换中”。无需手动编辑配置文件。

配置文件的位置取决于安装方式：

• 全局安装：$CLAUDE_CONFIG_DIR/hooks/peon-ping/config.json（默认 ~/.claude/hooks/peon-ping/config.json）
• 本地安装：./.claude/hooks/peon-ping/config.json

{
  "volume": 0.5,
  "categories": {
    "session.start": true,
    "task.acknowledge": true,
    "task.complete": true,
    "task.error": true,
    "input.required": true,
    "resource.limit": true,
    "user.spam": true
  }
}

独立控制

peon-ping 提供三种可自由组合的独立控制：

这意味着您可以：

• 保留声音但禁用桌面弹窗：peon notifications off

• 保留桌面弹窗但禁用声音：peon pause

• 启用手机推送而不启用桌面弹窗：将 desktop_notifications: false 和 mobile_notify.enabled: true

• volume: 0.0–1.0（安静到适合办公室）

• desktop_notifications: true/false — 独立于声音开关桌面通知弹窗（默认：true）。禁用后，声音仍会播放，但视觉弹窗会被屏蔽。移动通知不受影响。

• notification_style: "overlay" 或 "standard" — 控制桌面通知的显示方式（默认："overlay"）

  • overlay: 大型、醒目的横幅——macOS 上为 JXA Cocoa 叠加层，WSL/MSYS2 上为 Windows Forms 弹窗。点击叠加层会将终端窗口置顶（支持 Ghostty、Warp、iTerm2、Zed、Terminal.app）。在 iTerm2 中，点击不仅会将应用置顶，还会聚焦正确的标签页/窗格/窗口。
  • standard: 系统通知——macOS 上使用 terminal-notifier / osascript，WSL/MSYS2 上使用 Windows 通知气泡。安装 terminal-notifier 后（brew install terminal-notifier），点击标准通知会自动将终端窗口置顶（支持 Ghostty、Warp、iTerm2、Zed、Terminal.app）。在原生 Windows 系统中，点击通知气泡会将 IDE 或终端窗口置顶（支持 VS Code、Cursor、Windsurf、Windows Terminal、PowerShell）。当有多个窗口打开时，通知会通过基于 PID 的进程树匹配，精准定位到触发事件的窗口。

• overlay_theme: "jarvis"、"glass"、"sakura"，或省略以使用默认叠加层主题——仅适用于 macOS（默认：无）

  • jarvis: 圆形 HUD，带有旋转弧线、刻度标记和进度环。
  • glass: 玻璃质感面板，配有强调色条、进度线和时间戳。
  • sakura: 极简禅意花园，点缀盆景树与飘落的樱花花瓣动画。

• categories: 开关各个 CESP 声音分类（例如，"session.start": false 可禁用问候音）。

• annoyed_threshold / annoyed_window_seconds: 在 N 秒内收到多少条提示会触发 user.spam 彩蛋。

• silent_window_seconds: 对持续时间少于 N 秒的任务，抑制 task.complete 音效及通知。（例如，设置为 10 表示只有超过 10 秒的任务才会发出音效。）

• session_start_cooldown_seconds（数字，默认：30）：用于去重同时启动的多个工作区的问候音效（如同时打开 OpenCode 或 Cursor 并加载多个文件夹）。仅第一个会话的开始会播放问候音，此窗口内的后续会话则保持静音。设为 0 可禁用去重功能，始终播放问候音。

• suppress_subagent_complete（布尔值，默认：false）：当子代理会话结束时，抑制 task.complete 音效及通知。当 Claude Code 的任务工具并行调度多个子代理时，每个子代理都会触发完成音效——将其设置为 true，则只会听到父会话的完成音效。

• default_pack: 当没有更具体的规则适用时使用的回退包（默认："peon"）。取代了旧的 active_pack 键——现有配置会在 peon update 时自动迁移。

• path_rules: { "pattern": "...", "pack": "..." } 对象数组。根据工作目录，使用 glob 匹配规则（*、?）为会话分配特定包。优先匹配第一个规则。该规则优先于 pack_rotation 和 default_pack；但会被 session_override 分配覆盖。

  "path_rules": [
    { "pattern": "*/work/client-a/*", "pack": "glados" },
    { "pattern": "*/personal/*",      "pack": "peon" }
  ]
  

• pack_rotation: 包名数组（如 ["peon", "sc_kerrigan", "peasant"]）。当 pack_rotation_mode 为 random 或 round-robin 时使用。留空 [] 则仅使用 default_pack（或 path_rules）。

• pack_rotation_mode: "random"（默认）、"round-robin" 或 "session_override"。在 random/round-robin 模式下，每个会话会从 pack_rotation 中随机选择一个包。而在 session_override 模式下，可通过 /peon-ping-use <pack> 命令为每个会话指定包。无效或缺失的包会按层级顺序回退。（"agentskill" 被视为 "session_override" 的旧别名，仍可接受。）

• session_ttl_days（数字，默认：7）：使超过 N 天的会话级包分配失效。防止在使用 session_override 模式时 .state.json 文件无限增长。

• headphones_only（布尔值，默认：false）：仅在检测到耳机或外部音频设备时播放声音。启用后，若当前输出为内置扬声器，则会抑制声音——这在开放式办公室中非常实用。可通过 peon status 查看状态。支持 macOS（通过 system_profiler）和 Linux（通过 PipeWire wpctl 或 PulseAudio pactl）。

• suppress_sound_when_tab_focused（布尔值，默认：false）：当触发钩子事件的终端标签页为当前活动/聚焦的标签页时，跳过声音播放。后台标签页的声音仍会正常播放，作为提醒其他地方发生了某些事情。桌面和移动通知不受影响。适用于仅希望从未查看的标签页获取音频提示的情况。仅限 macOS（使用 osascript 检查前台应用及 iTerm2 标签页焦点）。

• meeting_detect 检测麦克风是否正在使用，并暂时抑制音频，直到麦克风不再使用为止。通知仍会显示。

• notification_position（字符串，默认："top-center"）：叠加式通知在屏幕上的显示位置。选项包括："top-left"、"top-center"、"top-right"、"bottom-left"、"bottom-center"、"bottom-right"。

• notification_dismiss_seconds（数字，默认：4）：叠加式通知在 N 秒后自动消失。设置为 0 可使通知持续显示，需手动关闭。

• notification_all_screens（布尔值，默认：true）：叠加式通知显示在所有屏幕上（true）或仅主屏幕上（false）。此前，主题叠加层（glass、jarvis、sakura）仅显示在单个屏幕上——使用这些主题的现有配置会自动迁移到 false。仅适用于 macOS。

• CLAUDE_SESSION_NAME 环境变量：在启动 claude 之前设置，为会话命名自定义名称。该名称会同时显示在桌面通知标题和终端标签页标题中。优先级高于所有基于配置的命名方式。示例：CLAUDE_SESSION_NAME="Auth Refactor" claude 或先执行 export CLAUDE_SESSION_NAME="Feature: Auth" 再运行 claude。由于 peon-ping 作为该 Claude 实例的子进程运行，每个终端会自动获得各自的标题。

• notification_title_override（字符串，默认：""）：覆盖通知标题中显示的项目名称。为空时，项目名称将自动从 /peon-ping-rename > CLAUDE_SESSION_NAME > .peon-label > notification_title_script > project_name_map > Git 仓库名 > 文件夹名中推断得出。

• notification_title_script（字符串，默认：""）：在事件发生时运行的 Shell 命令，用于动态计算项目名称。接收以下环境变量：PEON_SESSION_ID、PEON_CWD、PEON_HOOK_EVENT、PEON_SESSION_NAME。使用标准输出（截取前 50 个字符）；非零退出码则会传递到下一层次。示例："basename $PEON_CWD"。

• project_name_map（对象，默认：{}）：将目录路径映射为通知中显示的自定义项目标签。键为路径模式，值为显示名称。示例：{ "/home/user/work/client-a": "Client A" }。

• notification_templates（对象，默认：{}）：针对通知事件的自定义消息格式字符串。键为事件类型（stop、permission、error、idle、question），值为带变量替换的模板字符串。可用变量包括：{project}、{summary}、{tool_name}、{status}、{event}。示例：{ "stop": "{project}: {summary}", "permission": "{project}: {tool_name} 需要批准" }。

声音包选择层级

peon-ping 通过一个五层的优先级体系来决定使用哪个声音包。最先找到有效且已安装的声音包即为最终选择：

如果某一层引用了未安装的声音包，则会自动降级到下一层。

按项目分配声音包（path_rules）

根据目录路径为不同项目分配不同的声音包。可通过 CLI 或直接编辑 config.json 进行设置。

CLI（推荐）：

peon packs bind glados                     # 将 glados 绑定到当前目录
peon packs bind sc_kerrigan --pattern "*/services/*"  # 绑定到 glob 模式
peon packs bind duke_nukem --install       # 绑定并从注册表安装所需包
peon packs unbind                          # 移除当前目录的绑定
peon packs unbind --pattern "*/services/*" # 移除特定模式的绑定
peon packs bindings                        # 列出所有绑定

手动配置：

"path_rules": [
  { "pattern": "*/work/client-a/*", "pack": "glados" },
  { "pattern": "*/personal/*",      "pack": "peon" },
  { "pattern": "*/services/*",      "pack": "sc_kerrigan" }
]

规则使用 glob 匹配（*, ?）。优先匹配第一个规则。路径规则会覆盖 pack_rotation 和 default_pack，但会被 session_override 覆盖。

常见用例

只响声不弹窗

想要语音反馈但不想有视觉干扰？

peon notifications off

这将保持所有声音类别正常播放，同时屏蔽桌面通知横幅。若已配置移动通知，则仍会正常工作。

你也可以使用别名：

peon popups off

仅通知无声模式

想要视觉提醒但不要声音？

peon pause  # 或在配置中将 "enabled" 设置为 false

当 desktop_notifications: true 时，你会收到弹窗提示，但不会有声音。

完全静音

禁用所有功能：

peon pause
peon notifications off
peon mobile off

Peon 训练师

你的 peon 也是你的私人教练。内置 Pavel 风格的每日锻炼模式——那个曾经喊着“干活干活”的兽人现在会催促你做俯卧撑和深蹲。

快速开始

peon trainer on              # 启动训练模式
peon trainer goal 200        # 设置每日目标（默认：300/300）
# ... 编码一段时间后，peon 大约每 20 分钟提醒一次 ...
peon trainer log 25 pushups  # 记录完成情况
peon trainer log 30 squats
peon trainer status          # 查看进度

工作原理

训练提醒与你的编码会话同步进行。当你开始新会话时，peon 会立即鼓励你先做俯卧撑再写代码。随后，每活跃编码约 20 分钟，你就会听到 peon 催促你继续锻炼。无需后台守护进程。使用 peon trainer log 记录完成次数，进度将在午夜自动重置。

命令

Claude Code 技能

在 Claude Code 中，你可以在不退出对话的情况下记录锻炼次数：

/peon-ping-log 25 pushups
/peon-ping-log 30 squats

自定义语音提示

将你的音频文件放入 ~/.claude/hooks/peon-ping/trainer/sounds/ 目录：

trainer/sounds/session_start/  # 会话开场（“先做俯卧撑，再写代码！Zug zug!”）
trainer/sounds/remind/         # 提醒语句（“有什么需要做的吗？是的。俯卧撑！”）
trainer/sounds/log/            # 确认语句（“干活干活！肌肉可能正在变大！”）
trainer/sounds/complete/       # 庆祝语句（“Zug zug！人类完成了所有动作！”）
trainer/sounds/slacking/       # 失望语句（“Peon 非常失望。”）

更新 trainer/manifest.json 以注册你的音频文件。

MCP 服务器

peon-ping 内置了一个 MCP（模型上下文协议） 服务器，因此任何兼容 MCP 的 AI 助手都可以通过工具调用直接播放声音，无需额外钩子。

关键区别在于：由助手自行选择声音。助手不会在每个事件上自动播放固定声音，而是调用 play_sound 并明确指定所需的声音——例如构建失败时播放 duke_nukem/SonOfABitch，读取文件时播放 sc_kerrigan/IReadYou。

设置

在你的 MCP 客户端配置中添加以下内容（Claude Desktop、Cursor 等）：

{
  "mcpServers": {
    "peon-ping": {
      "command": "node",
      "args": ["/path/to/peon-ping/mcp/peon-mcp.js"]
    }
  }
}

若通过 Homebrew 安装：$(brew --prefix peon-ping)/libexec/mcp/peon-mcp.js。完整设置说明请参阅 mcp/README.md。

助手可执行的功能

需 Node.js 18+。由 @tag-assistant 贡献。

多IDE支持

peon-ping 可与任何支持钩子的代理型IDE配合使用。适配器会将IDE特定的事件转换为CESP标准。

Windows: 所有适配器都提供原生 PowerShell 版本（.ps1）。Windows 安装程序（install.ps1）会将这些文件复制到 ~/.claude/hooks/peon-ping/adapters/。文件系统监视器（Amp、Antigravity、Kimi）使用 .NET 的 FileSystemWatcher 而不是 fswatch/inotifywait——无需额外依赖。

OpenAI Codex 设置

Codex 支持通过适配器实现，并不会由 peon-ping-setup 自动注册。

Codex 适配器期望 peon-ping 运行时位于 ~/.claude/hooks/peon-ping/，即使你只使用 Codex 而不使用 Claude Code 也是如此。

设置：

1. 先安装 peon-ping 运行时：

   bash "$(brew --prefix peon-ping)"/libexec/install.sh --no-rc
   

   或使用标准安装脚本：

   curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash -s -- --no-rc
   

2. 在 ~/.codex/config.toml 中添加以下内容：

   notify = ["bash", "~/.claude/hooks/peon-ping/adapters/codex.sh"]
   

3. 重启 Codex。

如果你通过 Homebrew 安装，运行时文件会管理在 ~/.claude/hooks/peon-ping/ 目录下，而 Codex 适配器会将 Codex 的通知事件转发到该共享运行时环境中。

Amp 设置

这是用于 Amp（由 Sourcegraph 开发）的文件系统监视器适配器。Amp 不像 Claude Code 那样暴露事件钩子，因此此适配器会监视 Amp 在磁盘上的线程文件，并检测代理何时完成一轮交互。

设置：

1. 确保已安装 peon-ping（curl -fsSL https://peonping.com/install | bash）

2. 安装 fswatch（macOS）或 inotify-tools（Linux）：

   brew install fswatch        # macOS
   sudo apt install inotify-tools  # Linux
   

3. 启动监视器：

   bash ~/.claude/hooks/peon-ping/adapters/amp.sh        # 前台运行
   bash ~/.claude/hooks/peon-ping/adapters/amp.sh &       # 后台运行
   

事件映射：

• 新线程文件创建 → 欢迎音效（“准备好了吗？”、“是吗？”）
• 线程文件停止更新 + 代理完成一轮交互 → 完成音效（“工作，工作。”、“任务完成了！”）

工作原理：

适配器会监视 ~/.local/share/amp/threads/ 目录下的 JSON 文件变化。当线程文件停止更新（空闲超时为 1 秒），且最后一则消息来自助手且包含文本内容（而非待处理的工具调用）时，它会发出 Stop 事件——表示代理已完成工作，正在等待你的输入。

环境变量：

GitHub Copilot 设置

一个与 GitHub Copilot 兼容的 Shell 适配器，完全符合 CESP v1.0 标准。

设置步骤：

1. 确保已安装 peon-ping (curl -fsSL https://peonping.com/install | bash)

2. 在你的仓库（默认分支）中创建 .github/hooks/hooks.json 文件：

   {
     "version": 1,
     "hooks": {
       "sessionStart": [
         {
           "type": "command",
           "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh sessionStart"
         }
       ],
       "userPromptSubmitted": [
         {
           "type": "command",
           "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh userPromptSubmitted"
         }
       ],
       "postToolUse": [
         {
           "type": "command",
           "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh postToolUse"
         }
       ],
       "errorOccurred": [
         {
           "type": "command",
           "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh errorOccurred"
         }
       ]
     }
   }
   

3. 提交并合并到你的默认分支。这些钩子将在你下一次使用 Copilot 代理时生效。

事件映射：

• sessionStart → 欢迎音效（“准备好工作了吗？”、“是的吗？”）
• userPromptSubmitted → 第一条提示为问候，后续则触发垃圾信息检测
• postToolUse → 完成音效（“工作，工作。”、“任务完成了！”）
• errorOccurred → 错误音效（“我做不到。”）
• preToolUse → 跳过（噪音太大）
• sessionEnd → 无音效（session.end 尚未实现）

功能特性：

• 声音播放：通过 afplay（macOS）、pw-play/paplay/ffplay（Linux）实现——优先级顺序与 Shell 钩子相同。
• CESP 事件映射：GitHub Copilot 钩子映射到标准 CESP 类别（session.start、task.complete、task.error、user.spam）。
• 桌面通知：默认显示大型覆盖式横幅通知，或常规通知。
• 垃圾信息检测：若在 10 秒内连续收到 3 条以上快速提示，则触发 user.spam 语音提示。
• 会话跟踪：为每个 Copilot 会话 ID 分别标记会话。

OpenCode 设置

一个原生 TypeScript 插件，用于 OpenCode，完全符合 CESP v1.0 标准。

快速安装：

curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/opencode.sh | bash

安装程序会将 peon-ping.ts 复制到 ~/.config/opencode/plugins/，并在 ~/.config/opencode/peon-ping/config.json 中创建配置文件。插件包存储在共享的 CESP 路径下（~/.openpeon/packs/）。

功能特性：

• 声音播放：通过 afplay（macOS）、pw-play/paplay/ffplay（Linux）实现——优先级顺序与 Shell 钩子相同。
• CESP 事件映射：session.created、session.idle、session.error、permission.asked 以及快速提示检测等均映射到标准 CESP 类别。
• 桌面通知：默认显示大型覆盖式横幅通知（使用 JXA Cocoa，在所有屏幕上可见），或通过 terminal-notifier / osascript 发送常规通知。仅当终端未处于焦点状态时才会触发。
• 终端焦点检测：在发送通知前，通过 AppleScript 检查你的终端应用（Terminal、iTerm2、Warp、Alacritty、kitty、WezTerm、ghostty、Hyper）是否位于前台。
• 标签页标题：更新终端标签页以显示任务状态（“● 项目：正在工作…”、“✓ 项目：完成”、“✗ 项目：出错”）。
• 插件包切换：从配置中读取 default_pack（对于旧版配置则回退到 active_pack），并在运行时加载该包的 openpeon.json 清单文件。path_rules 可根据工作目录覆盖默认包。
• 防重复逻辑：避免同一类别中的声音连续两次播放。
• 垃圾信息检测：若在 10 秒内连续收到 3 条以上快速提示，则触发 user.spam 语音提示。

提示：安装 terminal-notifier（brew install terminal-notifier），以获得支持副标题和分组的更丰富通知。

bash <(curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/opencode/setup-icon.sh)

bash ~/.claude/hooks/peon-ping/adapters/opencode/setup-icon.sh

Kilo CLI 设置

一个原生 TypeScript 插件，用于 Kilo CLI，完全符合 CESP v1.0 标准。Kilo CLI 是 OpenCode 的一个分支，使用相同的插件系统——此安装程序会下载 OpenCode 插件，并针对 Kilo 进行补丁处理。

快速安装：

curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/kilo.sh | bash

安装程序会将 peon-ping.ts 复制到 ~/.config/kilo/plugins/，并在 ~/.config/kilo/peon-ping/config.json 中创建配置文件。插件包存储在共享的 CESP 路径下（~/.openpeon/packs/）。

功能特性： 与 OpenCode 适配器 相同——声音播放、CESP 事件映射、桌面通知、终端焦点检测、标签页标题、插件包切换、防重复逻辑以及垃圾信息检测。

Gemini CLI 设置

适用于 Gemini CLI 的 Shell 适配器，完全符合 CESP v1.0 规范。

设置步骤：

1. 确保已安装 peon-ping（curl -fsSL https://peonping.com/install | bash）。

2. 将以下钩子添加到你的 ~/.gemini/settings.json 文件中：

    {
      "hooks": {
        "SessionStart": [
          {
            "matcher": "startup",
            "hooks": [
              {
                "name": "peon-start",
                "type": "command",
                "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh SessionStart"
              }
            ]
          }
        ],
        "AfterAgent": [
          {
            "matcher": "*",
            "hooks": [
              {
                "name": "peon-after-agent",
                "type": "command",
                "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh AfterAgent"
              }
            ]
          }
        ],
        "AfterTool": [
          {
            "matcher": "*",
            "hooks": [
              {
                "name": "peon-after-tool",
                "type": "command",
                "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh AfterTool"
              }
            ]
          }
        ],
        "Notification": [
          {
            "matcher": "*",
            "hooks": [
              {
                "name": "peon-notification",
                "type": "command",
                "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh Notification"
              }
            ]
          }
        ]
      }
    }
   

事件映射：

• SessionStart（启动）→ 欢迎音效（“准备好了吗？”、“是的吗？”）
• AfterAgent → 任务完成音效（“工作，工作。”、“完成了！”）
• AfterTool → 成功 = 任务完成音效，失败 = 错误音效（“我做不到。”）
• Notification → 系统通知

Windsurf 设置

将以下内容添加到 ~/.codeium/windsurf/hooks.json（用户级别）或 .windsurf/hooks.json（工作区级别）：

{
  "hooks": {
    "post_cascade_response": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_cascade_response", "show_output": false }
    ],
    "pre_user_prompt": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh pre_user_prompt", "show_output": false }
    ],
    "post_write_code": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_write_code", "show_output": false }
    ],
    "post_run_command": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_run_command", "show_output": false }
    ]
  }
}

Kiro 设置

创建 ~/.kiro/agents/peon-ping.json 文件：

{
  "name": "peon-ping",
  "hooks": {
    "agentSpawn": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
    ],
    "userPromptSubmit": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
    ],
    "stop": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
    ]
  }
}

preToolUse 和 postToolUse 被有意排除——它们会在每次调用工具时触发，会产生大量噪音。

Rovo Dev CLI 设置

适用于 Atlassian 的 Rovo Dev CLI 的 Shell 适配器，完全符合 CESP v1.0 规范。

自动设置：

如果在运行 install.sh 或 peon-ping-setup 时存在 ~/.rovodev/config.yml 文件，则会自动注册事件钩子。

手动设置：

1. 确保已安装 peon-ping（curl -fsSL https://peonping.com/install | bash）。

2. 将以下内容添加到 ~/.rovodev/config.yml 文件中：

   eventHooks:
     events:
       - name: on_complete
         commands:
           - command: bash ~/.claude/hooks/peon-ping/adapters/rovodev.sh on_complete
       - name: on_error
         commands:
           - command: bash ~/.claude/hooks/peon-ping/adapters/rovodev.sh on_error
       - name: on_tool_permission
         commands:
           - command: bash ~/.claude/hooks/peon-ping/adapters/rovodev.sh on_tool_permission
   

3. 重启 Rovo Dev CLI 以使钩子生效。

事件映射：

• on_complete → 完成音效（“工作，工作。”、“完成了！”）
• on_error → 错误音效（“我做不到。”、“该死！”）
• on_tool_permission → 权限提示音效（“有什么需要做的吗？”、“嗯？”）

功能：

• 声音播放 通过 afplay（macOS）、pw-play/paplay/ffplay（Linux）实现——与 Shell 钩子具有相同的优先级链。
• CESP 事件映射 — Rovo Dev 事件映射到标准 CESP 类别（task.complete、task.error、input.required）。
• 桌面通知 — 默认为大型覆盖式横幅，或使用标准通知。
• 防抖动 — 抑制快速连续完成时产生的重复音效。

Kimi Code 设置

适用于 Kimi Code CLI（MoonshotAI）的文件系统监视器适配器。Kimi Code 会将 Wire Mode 事件写入 ~/.kimi/sessions/ 目录——此适配器作为后台守护进程监视这些文件，并将事件转换为 CESP 格式。

# 安装（启动后台守护进程）
bash ~/.claude/hooks/peon-ping/adapters/kimi.sh --install

# 查看状态 / 停止
bash ~/.claude/hooks/peon-ping/adapters/kimi.sh --status
bash ~/.claude/hooks/peon-ping/adapters/kimi.sh --uninstall

需要在 macOS 上安装 fswatch（brew install fswatch），或在 Linux 上安装 inotifywait（apt install inotify-tools）。curl | bash 安装程序会自动检测 Kimi Code 并启动守护进程。

事件映射：

• 新会话 → 欢迎音效（“准备好了吗？”、“是的吗？”）
• 代理回合结束 → 完成音效（“工作，工作。”、“完成了！”）
• 上下文压缩 → 令牌限制音效
• 子代理生成 → 子代理跟踪音效

远程开发（SSH / Devcontainers / Codespaces）

在远程服务器或容器内进行编码？peon-ping 会自动检测 SSH 会话、Devcontainers 和 Codespaces，然后通过你本地机器上运行的轻量级中继路由音频和通知。

SSH 设置

1. 在你的本地机器上，启动中继：

   peon relay --daemon
   

2. 使用端口转发进行 SSH 连接：

   ssh -R 19998:localhost:19998 your-server
   

3. 在远程主机上安装 peon-ping——它会自动检测 SSH 会话，并通过转发的端口将音频请求发送回你本地的中继。

就是这样。声音将在你的笔记本电脑上播放，而不是在远程服务器上。

可选的 SSH 路由模式：

peon ssh-audio relay   # 默认，始终使用中继
peon ssh-audio auto    # 尝试使用中继，若失败则回退到 SSH 主机本地播放
peon ssh-audio local   # 始终在 SSH 主机上播放

Devcontainers / Codespaces

无需端口转发——peon-ping 会自动检测 REMOTE_CONTAINERS 和 CODESPACES 环境变量，并将音频路由到 host.docker.internal:19998。只需在你的主机上运行 peon relay --daemon 即可。

中继命令

peon relay                # 在前台启动中继
peon relay --daemon       # 在后台启动
peon relay --stop         # 停止后台中继
peon relay --status       # 检查中继是否正在运行
peon relay --port=12345   # 自定义端口（默认：19998）
peon relay --bind=0.0.0.0 # 监听所有接口（安全性较低）

环境变量：PEON_RELAY_PORT、PEON_RELAY_HOST、PEON_RELAY_BIND。

如果 peon-ping 检测到 SSH 或容器会话，但无法连接到中继，则会在 SessionStart 事件时打印设置说明。

基于分类的 API（用于轻量级远程钩子）

中继支持基于分类的端点，可在服务器端处理声音选择。这对于未安装 peon-ping 的远程机器非常有用——远程钩子只需发送一个分类名称，中继就会从当前激活的声音包中随机选择一个声音播放。

端点：

远程钩子示例（scripts/remote-hook.sh）：

#!/bin/bash
RELAY_URL="${PEON_RELAY_URL:-http://127.0.0.1:19998}"
EVENT=$(cat | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('hook_event_name',''))" 2>/dev/null)
case "$EVENT" in
  SessionStart)      CATEGORY="session.start" ;;
  Stop)              CATEGORY="task.complete" ;;
  PermissionRequest) CATEGORY="input.required" ;;
  *)                 exit 0 ;;
esac
curl -sf "${RELAY_URL}/play?category=${CATEGORY}" >/dev/null 2>&1 &

将此脚本复制到您的远程机器，并在 ~/.claude/settings.json 中注册：

{
  "hooks": {
    "SessionStart": [{"command": "bash /path/to/remote-hook.sh"}],
    "Stop": [{"command": "bash /path/to/remote-hook.sh"}],
    "PermissionRequest": [{"command": "bash /path/to/remote-hook.sh"}]
  }
}

中继会读取您本地机器上的 config.json 文件以获取当前激活的声音包和音量，加载该声音包的清单，并在避免重复的情况下随机选择一个声音。

移动通知

当任务完成或需要关注时，您可以在手机上收到推送通知——这在您离开办公桌时非常有用。

快速入门（ntfy.sh — 免费，无需账号）

1. 在您的手机上安装 ntfy 应用程序
2. 在应用中订阅一个唯一的主题（例如 my-peon-notifications）
3. 运行：

   peon mobile ntfy my-peon-notifications
   

还支持 Pushover 和 Telegram：

peon mobile pushover <user_key> <app_token>
peon mobile telegram <bot_token> <chat_id>

移动命令

peon mobile on            # 启用移动通知
peon mobile off           # 禁用移动通知
peon mobile status        # 显示当前配置
peon mobile test          # 发送测试通知

移动通知会在每次事件发生时触发，无论窗口是否处于焦点状态——它们与桌面通知和声音是独立的。

声音包

涵盖魔兽争霸、星际争霸、红色警戒、传送门、塞尔达传说、Dota 2、地狱特工2、上古卷轴等共 165 个声音包。默认安装包含 5 个精选声音包：

浏览所有带有音频预览的声音包 → openpeon.com/packs

使用 --all 可以安装所有声音包，或者随时切换声音包：

peon packs use glados             # 切换到特定声音包
peon packs use --install glados   # 一步完成安装并切换
peon packs next                   # 循环切换到下一个声音包
peon packs list                   # 列出所有已安装的声音包
peon packs list --registry        # 浏览所有可用的声音包
peon packs install glados,murloc  # 安装指定声音包
peon packs install --all          # 安装注册表中的所有声音包

想添加自己的声音包吗？请参阅 openpeon.com/create 上的完整指南 或 CONTRIBUTING.md。

调试

当声音无法播放或通知未出现时，结构化的调试日志可以帮助您追踪钩子调用过程中究竟发生了什么。

启用调试日志

peon debug on             # 启用——日志写入 ~/.claude/hooks/peon-ping/logs/
peon debug off            # 禁用
peon debug status         # 显示状态、日志目录、文件数量、总大小

您也可以通过设置环境变量 PEON_DEBUG=1 来在不更改配置的情况下为每次调用启用调试日志。

阅读日志

peon logs                 # 今日日志的最后 50 行
peon logs --last 100      # 所有日志文件中的最后 100 行
peon logs --session <ID>  # 按会话 ID 筛选今日日志
peon logs --session <ID> --all  # 在所有日志文件中搜索会话 ID
peon logs --clear         # 删除所有日志文件（需确认）

日志格式

每条日志都是一个结构化的键值记录：

2026-03-26T14:32:01.042 [config] inv=a3f1 loaded=/path/to/config.json volume=0.5 pack=peon enabled=True
2026-03-26T14:32:01.045 [event] inv=a3f1 hook_event=Stop cesp=task.complete session=abc123
2026-03-26T14:32:01.048 [sound] inv=a3f1 file=work-work.wav label="Work, work." category=task.complete
2026-03-26T14:32:01.120 [play] inv=a3f1 player=afplay file=work-work.wav
2026-03-26T14:32:01.125 [notify] inv=a3f1 title="peon: done" body="Work, work."

• inv — 唯一的 4 字符调用 ID，用于链接单次钩子调用的所有阶段
• 阶段：[config]、[event]、[sound]、[play]、[notify]——分别代表钩子流程中的各个阶段
• 包含空格或特殊字符的值会被引号括起来

常见故障示例

配置键

日志存储在 ~/.claude/hooks/peon-ping/logs/peon-ping-YYYY-MM-DD.log（每天一个文件）。当创建新一天的日志时，旧日志会根据 debug_retention_days 自动被清除。

卸载

macOS/Linux：

bash "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/uninstall.sh        # 全局
bash .claude/hooks/peon-ping/uninstall.sh           # 项目本地

Windows（PowerShell）：

# 标准卸载（删除音效前会提示）
powershell -File "$env:USERPROFILE\.claude\hooks\peon-ping\uninstall.ps1"

# 保留音效包（移除其他所有内容）
powershell -File "$env:USERPROFILE\.claude\hooks\peon-ping\uninstall.ps1" -KeepSounds

要求

• macOS — afplay（内置），JXA Cocoa 叠加层或 AppleScript 用于通知
• Linux — 以下之一：pw-play、paplay、ffplay、mpv、play（SoX）或 aplay；notify-send 用于通知
• Windows — 原生 PowerShell，配备 MediaPlayer 和 WinForms（无需 WSL），或 WSL2
• MSYS2 / Git Bash — python3、cygpath（内置）；音频可通过 ffplay/mpv/play 或 PowerShell 备用方案实现
• 所有平台 — python3（Windows 原生版本除外）
• SSH/远程 — 远程主机上需安装 curl
• IDE — 支持钩子的 Claude Code、Amp，或通过 适配器 支持的任何 IDE

工作原理

peon.sh 是一个注册了 SessionStart、SessionEnd、SubagentStart、Stop、Notification、PermissionRequest、PostToolUseFailure 和 PreCompact 事件的 Claude Code 钩子。每次触发事件时：

1. 事件映射 — 内嵌的 Python 代码块将钩子事件映射到 CESP 音效类别（如 session.start、task.complete、input.required 等）。
2. 音效选择 — 从当前激活的音效包清单中随机选取一条语音，避免重复。
3. 音频播放 — 通过 afplay（macOS）、PowerShell 的 MediaPlayer（WSL2/MSYS2 备用方案）或 pw-play/paplay/ffplay/mpv/aplay（Linux/MSYS2）异步播放音效。
4. 通知 — 更新终端标签页标题，并在终端未聚焦时发送桌面通知。
5. 远程路由 — 在 SSH 会话、Devcontainers 和 Codespaces 中，音频和通知请求会通过 HTTP 转发到您本地机器上的 中继服务器。

音效包会在安装时从 OpenPeon 注册表 下载。官方音效包托管在 PeonPing/og-packs 中。音效文件归各自发行方（Blizzard、Valve、EA 等）所有，仅以合理使用原则分发，用于个人通知目的。

链接

• @peonping on X — 最新动态与公告
• peonping.com — 项目主页
• openpeon.com — CESP 规范、音效包浏览器、集成指南、创作指南
• OpenPeon 注册表 — 音效包注册表（GitHub Pages）
• og-packs — 官方音效包
• peon-pet — macOS 桌面宠物（兽人精灵，对钩子事件作出反应）
• 许可证（MIT）

支持本项目

• Venmo：@garysheng
• 社区代币（自行研究/自娱自乐）：有人在 Base 上创建了 $PEON 代币——我们从中获得交易手续费，用于支持开发。0xf4ba744229afb64e2571eef89aacec2f524e8ba3

Peon-Ping 快速上手指南

Peon-Ping 是一款专为 AI 编程助手（如 Claude Code、Cursor、GitHub Copilot 等）设计的通知工具。当 AI 完成任务、需要权限或报错时，它会播放经典游戏语音（如魔兽、星际、传送门等）并显示屏幕横幅，帮助你保持专注流。

环境准备

系统要求

支持以下操作系统：

• macOS
• Linux (包括 WSL2)
• Windows (包括 MSYS2)
• SSH / DevContainers / Codespaces (远程开发环境)

前置依赖

• WSL2/Debian 用户注意：若使用非 WAV 格式的音效包，必须安装 ffmpeg。

  sudo apt update && sudo apt install -y ffmpeg
  

• Nix 用户：无需额外依赖，可直接通过 Nix 运行。

安装步骤

推荐根据你的系统选择以下一种方式安装：

方式 1：Homebrew (推荐 macOS/Linux 用户)

brew install PeonPing/tap/peon-ping

安装完成后，运行以下命令注册钩子并下载默认音效包：

peon-ping-setup

方式 2：一键脚本 (macOS, Linux, WSL2)

curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash

方式 3：PowerShell (Windows 用户)

在 PowerShell 中运行：

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.ps1" -UseBasicParsing | Invoke-Expression

默认安装魔兽、星际、传送门三个精选包。如需自定义安装包，可访问官网交互选择。

方式 4：Nix (macOS, Linux)

直接运行（无需安装）：

nix run github:PeonPing/peon-ping -- status

或安装到用户配置：

nix profile install github:PeonPing/peon-ping

基本使用

安装完成后，Peon-Ping 会自动集成到支持的 AI 工具中。以下是常用操作：

1. 验证状态

检查服务是否正常运行及当前配置：

peon status

查看详细状态（包含通知设置、耳机检测等）：

peon status --verbose

2. 临时静音/恢复

在会议或结对编程时需要暂时关闭通知：

# 暂停通知
peon pause

# 恢复通知
peon resume

或在 Claude Code 中直接使用斜杠命令：

/peon-ping-toggle

3. 管理音效包

查看已安装的音效包：

peon packs list

切换音效包（例如切换到 GLaDOS 语音）：

peon packs use glados

浏览并安装更多音效包：

peon packs list --registry
peon packs install <包名>

4. 调节音量

查看当前音量：

peon volume

设置音量（0.0 到 1.0）：

peon volume 0.7

5. 触发测试

发送一条测试通知以确认配置生效：

peon notifications test

典型工作流

1. 启动你的 AI 编程助手（如 claude 或 cursor）。
2. 当 AI 开始工作时，你会听到 "Ready to work?"。
3. 当任务完成时，听到 "Work, work." 并看到屏幕横幅。
4. 若 AI 需要输入，会播放提示音提醒你切换窗口。