[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-PeonPing--peon-ping":3,"tool-PeonPing--peon-ping":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",153609,2,"2026-04-13T11:34:59",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":72,"owner_avatar_url":73,"owner_bio":74,"owner_company":75,"owner_location":75,"owner_email":75,"owner_twitter":72,"owner_website":76,"owner_url":77,"languages":78,"stars":103,"forks":104,"last_commit_at":105,"license":106,"difficulty_score":32,"env_os":107,"env_gpu":108,"env_ram":109,"env_deps":110,"category_tags":114,"github_topics":115,"view_count":32,"oss_zip_url":75,"oss_zip_packed_at":75,"status":17,"created_at":124,"updated_at":125,"faqs":126,"releases":156},7199,"PeonPing\u002Fpeon-ping","peon-ping","Warcraft III Peon voice notifications (+ more!) for Claude Code, Codex, IDEs, and any AI agent. Stop babysitting your terminal. Employ a Peon today.","peon-ping 是一款专为开发者设计的趣味通知工具，旨在解决在使用 AI 编程助手（如 Claude Code、GitHub Copilot、Cursor 等）时，因等待任务完成或权限确认而频繁查看终端、导致注意力分散的痛点。它不再让你枯燥地“盯着”屏幕，而是当 AI 代理需要关注时，通过播放《魔兽争霸》、《星际争霸》、《传送门》等经典游戏的角色语音，并配合醒目的屏幕横幅，主动向你发出提醒。\n\n这款工具特别适合广大软件工程师、全栈开发者以及重度依赖 AI 辅助编码的技术人员。无论是本地开发、远程 SSH 连接，还是在 WSL2 和各类容器中工作，peon-ping 都能无缝集成。其独特的技术亮点在于支持跨平台（macOS、Linux、Windows）和多 IDE 适配，并引入了 MCP（模型上下文协议）服务器机制，允许 AI 代理根据上下文智能选择特定的音效进行反馈。此外，它还提供了丰富的声音包自定义选项和移动端通知支持。通过 peon-ping，你可以更从容地离开终端去处理其他事务，待听到熟悉的\"Work work!\"语音时再回归，从而有效保护心流状态，提升开发效率与乐趣。","# peon-ping\n\u003Cdiv align=\"center\">\n\n**English** | [한국어](README_ko.md) | [中文](README_zh.md) | [日本語](README_ja.md)\n\n![macOS](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FmacOS-blue) ![WSL2](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FWSL2-blue) ![Linux](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLinux-blue) ![Windows](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FWindows-blue) ![MSYS2](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMSYS2-blue) ![SSH](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSSH-blue)\n![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-green)\n\n![Claude Code](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude_Code-hook-ffab01) ![Amp](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FAmp-adapter-ffab01) ![Gemini CLI](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGemini_CLI-adapter-ffab01) ![GitHub Copilot](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitHub_Copilot-adapter-ffab01) ![Codex](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCodex-adapter-ffab01) ![Cursor](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCursor-adapter-ffab01) ![OpenCode](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FOpenCode-adapter-ffab01) ![Kilo CLI](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FKilo_CLI-adapter-ffab01) ![Kiro](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FKiro-adapter-ffab01) ![Kimi Code](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FKimi_Code-adapter-ffab01) ![Windsurf](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FWindsurf-adapter-ffab01) ![Antigravity](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FAntigravity-adapter-ffab01) ![OpenClaw](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FOpenClaw-adapter-ffab01) ![Rovo Dev CLI](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FRovo_Dev_CLI-adapter-ffab01) ![DeepAgents](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDeepAgents-adapter-ffab01)\n\n**Game character voice lines + visual overlay notifications when your AI coding agent needs attention — or let the agent pick its own sound via MCP.**\n\nAI coding agents don't notify you when they finish or need permission. You tab away, lose focus, and waste 15 minutes getting back into flow. peon-ping fixes this with voice lines and bold on-screen banners from Warcraft, StarCraft, Portal, Zelda, and more — works with **Claude Code**, **Amp**, **GitHub Copilot**, **Codex**, **Cursor**, **OpenCode**, **Kilo CLI**, **Kiro**, **Kimi Code**, **Windsurf**, **Google Antigravity**, **Rovo Dev CLI**, **DeepAgents**, and any MCP client.\n\n**See it in action** → [peonping.com](https:\u002F\u002Fpeonping.com\u002F)\n\n\u003Cvideo src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F149b6d15-65c2-41f2-9b56-13575ff8364b\" autoplay loop muted playsinline width=\"400\">\u003C\u002Fvideo>\n\n\u003C\u002Fdiv>\n\n---\n\n- [Install](#install)\n- [What you'll hear](#what-youll-hear)\n- [Quick controls](#quick-controls)\n- [Configuration](#configuration)\n- [Peon Trainer](#peon-trainer)\n- [MCP server](#mcp-server)\n- [Multi-IDE support](#multi-ide-support)\n- [Remote development](#remote-development-ssh--devcontainers--codespaces)\n- [Mobile notifications](#mobile-notifications)\n- [Sound packs](#sound-packs)\n- [Debugging](#debugging)\n- [Uninstall](#uninstall)\n- [Requirements](#requirements)\n- [How it works](#how-it-works)\n- [Links](#links)\n\n---\n\n## Install\n\n### Option 1: Homebrew (recommended)\n\n```bash\nbrew install PeonPing\u002Ftap\u002Fpeon-ping\n```\n\nThen run `peon-ping-setup` to register hooks and download sound packs. macOS and Linux.\n\n### Option 2: Installer script (macOS, Linux, WSL2)\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.sh | bash\n```\n\n⚠️ In WSL2, **ffmpeg** must be installed to use sound packs that use formats other than **WAV**. In Debian distros, install with\n\n```sh\nsudo apt update; sudo apt install -y ffmpeg\n```\n\n### Option 3: Installer for Windows\n\n```powershell\nInvoke-WebRequest -Uri \"https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.ps1\" -UseBasicParsing | Invoke-Expression\n```\n\nInstalls 5 curated packs by default (Warcraft, StarCraft, Portal). Re-run to update while preserving config\u002Fstate. Or **[pick your packs interactively at peonping.com](https:\u002F\u002Fpeonping.com\u002F#picker)** and get a custom install command.\n\nUseful installer flags:\n\n- `--all` — install all available packs\n- `--packs=peon,sc_kerrigan,...` — install specific packs only\n- `--local` — install packs, config, and hooks into `.\u002F.claude\u002F` for the current project\n- `--global` — explicit global install (same as default)\n- `--init-local-config` — create `.\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fconfig.json` only\n\n`--local` does not modify your shell rc files (no global `peon` alias\u002Fcompletion injection). Hooks are registered in the project-level `.\u002F.claude\u002Fsettings.json` with absolute paths so they work from any working directory within the project.\n\nExamples:\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.sh | bash -s -- --all\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.sh | bash -s -- --packs=peon,sc_kerrigan\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.sh | bash -s -- --local\n```\n\nIf a global install exists and you install local (or vice versa), the installer prompts you to remove the existing one to avoid conflicts.\n\n### Option 4: Clone and inspect first\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping.git\ncd peon-ping\n.\u002Finstall.sh\n```\n\n### Option 5: Nix (macOS, Linux)\n\nRun directly from source without installing:\n\n```bash\nnix run github:PeonPing\u002Fpeon-ping -- status\nnix run github:PeonPing\u002Fpeon-ping -- packs install peon\n```\n\nOr install to your profile:\n\n```bash\nnix profile install github:PeonPing\u002Fpeon-ping\n```\n\nDevelopment shell (bats, shellcheck, nodejs):\n\n```bash\nnix develop  # or use direnv\n```\n\n#### Home Manager module (declarative configuration)\n\nFor reproducible setups, use the Home Manager module:\n\n```nix\n# In your home.nix or flake.nix\n{ inputs, pkgs, ... }:\n\nlet\n  peonCursorAdapterPath = \"${inputs.peon-ping.packages.${pkgs.system}.default}\u002Fshare\u002Fpeon-ping\u002Fadapters\u002Fcursor.sh\";\nin {\n  imports = [ inputs.peon-ping.homeManagerModules.default ];\n\n  programs.peon-ping = {\n    enable = true;\n    package = inputs.peon-ping.packages.${pkgs.system}.default;\n\n    settings = {\n      default_pack = \"glados\";\n      volume = 0.7;\n      enabled = true;\n      desktop_notifications = true;\n      categories = {\n        \"session.start\" = true;\n        \"task.complete\" = true;\n        \"task.error\" = true;\n        \"input.required\" = true;\n        \"resource.limit\" = true;\n        \"user.spam\" = true;\n      };\n    };\n\n    # Install packs from og-packs (simple string notation)\n    # and custom sources (attrset with name + src)\n    installPacks = [\n      \"peon\"\n      \"glados\"\n      \"sc_kerrigan\"\n      # Custom pack from GitHub (openpeon.com registry)\n      {\n        name = \"mr_meeseeks\";\n        src = pkgs.fetchFromGitHub {\n          owner = \"kasperhendriks\";\n          repo = \"openpeon-mrmeeseeks\";\n          rev = \"main\";  # or use a commit hash for reproducibility\n          sha256 = \"sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=\";\n        };\n      }\n    ];\n    enableZshIntegration = true;\n  };\n\n  # Cursor hooks\n  home.file.\".cursor\u002Fhooks.json\".text = builtins.toJSON {\n    version = 1;\n    hooks = {\n      afterAgentResponse = [{ command = \"bash ${peonCursorAdapterPath} afterAgentResponse\"; }];\n      stop               = [{ command = \"bash ${peonCursorAdapterPath} stop\"; }];\n    };\n  };\n}\n```\n\n**Sound pack installation**: The `installPacks` option supports two formats:\n- **Simple strings** (e.g., `\"peon\"`, `\"glados\"`) — fetched from the [og-packs](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fog-packs) repository\n- **Custom sources** — attrset with `name` and `src` fields, where `src` can be any Nix fetcher result (e.g., `pkgs.fetchFromGitHub`)\n\nFor packs listed on [openpeon.com](https:\u002F\u002Fopenpeon.com\u002F), find the GitHub repository link and use `pkgs.fetchFromGitHub`:\n```nix\n{\n  name = \"pack_name\";\n  src = pkgs.fetchFromGitHub {\n    owner = \"github-owner\";\n    repo = \"repo-name\";\n    rev = \"main\";  # or a commit hash\u002Ftag\n    sha256 = \"\";   # Leave empty first, Nix will tell you the correct hash\n  };\n}\n```\n\n**IDE hooks**: peon-ping Home Manager module will not setup your IDE hooks to avoid conflicting updates. You must define these hooks yourself (see example above) depending on how you usually manage your IDE configuration.\n- peon-ping provide adapters scripts for various IDE such as `cursor.sh` - see [`adapters\u002F`](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Ftree\u002Fmain\u002Fadapters)\n- You need to call them as your hook such command like\n  ```sh\n  ${inputs.peon-ping.packages.${pkgs.system}.default}\u002Fshare\u002Fpeon-ping\u002Fadapters\u002F$YOUR_IDE.sh EVENT_NAME\n  ```\n  See Cursor example above\n\n## What you'll hear\n\n| Event | CESP Category | Examples |\n|---|---|---|\n| Session starts | `session.start` | *\"Ready to work?\"*, *\"Yes?\"*, *\"What you want?\"* |\n| Task finishes | `task.complete` | *\"Work, work.\"*, *\"I can do that.\"*, *\"Okie dokie.\"* |\n| Permission needed | `input.required` | *\"Something need doing?\"*, *\"Hmm?\"*, *\"What you want?\"* |\n| Tool or command error | `task.error` | *\"I can't do that.\"*, *\"Son of a bitch!\"* |\n| Agent acknowledged task | `task.acknowledge` | *\"I read you.\"*, *\"On it.\"* *(disabled by default)* |\n| Rate or token limit hit | `resource.limit` | *\"Zug zug.\"* *(pack dependent)* |\n| Rapid prompts (3+ in 10s) | `user.spam` | *\"Me busy, leave me alone!\"* |\n\nPlus **large overlay banners** on every screen (macOS\u002FWSL\u002FMSYS2) and terminal tab titles (`● project: done`) — you'll know something happened even if you're in another app.\n\npeon-ping implements the [Coding Event Sound Pack Specification (CESP)](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) — an open standard for coding event sounds that any agentic IDE can adopt.\n\n## Quick controls\n\nNeed to mute sounds and notifications during a meeting or pairing session? Two options:\n\n| Method | Command | When |\n|---|---|---|\n| **Slash command** | `\u002Fpeon-ping-toggle` | While working in Claude Code |\n| **CLI** | `peon toggle` | From any terminal tab |\n\nOther CLI commands:\n\n```bash\npeon pause                # Mute sounds\npeon resume               # Unmute sounds\npeon mute                 # Alias for 'pause'\npeon unmute               # Alias for 'resume'\npeon status               # Check if paused or active (concise)\npeon status --verbose     # Show full details (notifications, headphones, IDEs, etc.)\npeon volume               # Show current volume\npeon volume 0.7           # Set volume (0.0–1.0)\npeon rotation             # Show current rotation mode\npeon rotation random      # Set rotation mode (random|round-robin|session_override)\npeon packs list           # List installed sound packs\npeon packs list --registry # Browse all available packs in the registry\npeon packs community      # List all registry packs grouped by trust tier (Windows)\npeon packs search \u003Cquery> # Search registry packs by name (Windows)\npeon packs install \u003Cp1,p2> # Install packs from the registry\npeon packs install --all  # Install all packs from the registry\npeon packs install-local \u003Cpath> # Install a pack from a local directory\npeon packs use \u003Cname>     # Switch to a specific pack (auto-installs from registry on Windows)\npeon packs use --install \u003Cname>  # Switch to pack, installing from registry if needed\npeon packs next           # Cycle to the next pack\npeon packs remove \u003Cp1,p2> # Remove specific packs\npeon packs bind \u003Cname>    # Bind a pack to the current directory\npeon packs bind --pattern \u003Cpath> # Bind a pack to a directory pattern, e.g. \"*\u002Fservices\"\npeon packs unbind         # Remove the current directory\npeon packs bindings       # List all assigned bindings\npeon notifications on     # Enable desktop notifications\npeon notifications off    # Disable desktop notifications\npeon notifications overlay   # Use large overlay banners (default)\npeon notifications standard  # Use standard system notifications\npeon notifications test      # Send a test notification\npeon notifications position [pos]    # Get\u002Fset notification position (top-left, top-center, top-right, bottom-left, bottom-center, bottom-right)\npeon notifications dismiss [N]       # Get\u002Fset auto-dismiss time in seconds (0 = persistent)\npeon notifications label [text|reset] # Get\u002Fset project label override for notifications\npeon notifications template [key] [fmt]  # Get\u002Fset\u002Freset message templates (keys: stop, permission, error, idle, question)\npeon preview              # Play all sounds from session.start\npeon preview \u003Ccategory>   # Play all sounds from a specific category\npeon preview --list       # List all categories in the active pack\npeon mobile ntfy \u003Ctopic>  # Set up phone notifications (free)\npeon mobile off           # Disable phone notifications\npeon mobile test          # Send a test notification\npeon debug on             # Enable debug logging\npeon debug off            # Disable debug logging\npeon debug status         # Show debug state, log directory, file count, total size\npeon logs                 # Show last 50 lines of today's log\npeon logs --last N        # Show last N lines across all log files\npeon logs --session ID    # Filter today's log by session ID\npeon logs --session ID --all  # Search all log files for session ID\npeon logs --clear         # Delete all log files (with confirmation)\npeon relay --daemon       # Start audio relay (for SSH\u002Fdevcontainer)\npeon relay --stop         # Stop background relay\n```\n\nAvailable CESP categories for `peon preview`: `session.start`, `task.acknowledge`, `task.complete`, `task.error`, `input.required`, `resource.limit`, `user.spam`. (Extended categories `session.end` and `task.progress` are defined in the CESP spec and supported by pack manifests, but not currently triggered by built-in hook events.)\n\nTab completion is supported — type `peon packs use \u003CTAB>` to see available pack names.\n\nPausing mutes sounds and desktop notifications instantly. Persists across sessions until you resume. Tab titles remain active when paused.\n\n## Configuration\n\npeon-ping installs slash commands in Claude Code:\n\n- `\u002Fpeon-ping-toggle` — mute\u002Funmute sounds\n- `\u002Fpeon-ping-config` — change any setting (volume, packs, categories, etc.)\n- `\u002Fpeon-ping-rename \u003Cname>` — give this session a custom name shown in notification titles and the terminal tab title (zero tokens, hook-intercepted); no argument resets to auto-detect\n\nYou can also just ask Claude to change settings for you — e.g. \"enable round-robin pack rotation\", \"set volume to 0.3\", or \"add glados to my pack rotation\". No need to edit config files manually.\n\nConfig location depends on install mode:\n\n- Global install: `$CLAUDE_CONFIG_DIR\u002Fhooks\u002Fpeon-ping\u002Fconfig.json` (default `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fconfig.json`)\n- Local install: `.\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fconfig.json`\n\n```json\n{\n  \"volume\": 0.5,\n  \"categories\": {\n    \"session.start\": true,\n    \"task.acknowledge\": true,\n    \"task.complete\": true,\n    \"task.error\": true,\n    \"input.required\": true,\n    \"resource.limit\": true,\n    \"user.spam\": true\n  }\n}\n```\n\n### Independent Controls\n\npeon-ping has three independent controls that can be mixed and matched:\n\n| Config Key | Controls | Affects Sounds | Affects Desktop Popups | Affects Mobile Push |\n|------------|----------|----------------|------------------------|---------------------|\n| `enabled` | Master audio switch | ✅ Yes | ❌ No | ❌ No |\n| `desktop_notifications` | Desktop popup banners | ❌ No | ✅ Yes | ❌ No |\n| `mobile_notify.enabled` | Phone push notifications | ❌ No | ❌ No | ✅ Yes |\n\nThis means you can:\n- Keep sounds but disable desktop popups: `peon notifications off`\n- Keep desktop popups but disable sounds: `peon pause`\n- Enable mobile push without desktop popups: set `desktop_notifications: false` and `mobile_notify.enabled: true`\n\n- **volume**: 0.0–1.0 (quiet enough for the office)\n- **desktop_notifications**: `true`\u002F`false` — toggle desktop notification popups independently from sounds (default: `true`). When disabled, sounds continue playing but visual popups are suppressed. Mobile notifications are unaffected.\n- **notification_style**: `\"overlay\"` or `\"standard\"` — controls how desktop notifications appear (default: `\"overlay\"`)\n  - **overlay**: large, visible banners — JXA Cocoa overlay on macOS, Windows Forms popup on WSL\u002FMSYS2. Clicking the overlay focuses your terminal (supports Ghostty, Warp, iTerm2, Zed, Terminal.app). On iTerm2, clicking focuses the correct tab\u002Fpane\u002Fwindow — not just the app.\n  - **standard**: system notifications — [`terminal-notifier`](https:\u002F\u002Fgithub.com\u002FjulienXX\u002Fterminal-notifier) \u002F `osascript` on macOS, Windows toast on WSL\u002FMSYS2. When `terminal-notifier` is installed (`brew install terminal-notifier`), clicking a standard notification focuses your terminal automatically (supports Ghostty, Warp, iTerm2, Zed, Terminal.app). On native Windows, clicking a toast notification focuses the IDE or terminal window (supports VS Code, Cursor, Windsurf, Windows Terminal, PowerShell). With multiple windows open, the notification targets the exact window that originated the event via PID-based process tree matching.\n- **overlay_theme**: `\"jarvis\"`, `\"glass\"`, `\"sakura\"`, or omit for the default overlay — macOS only (default: none)\n  - **jarvis**: circular HUD with rotating arcs, graduation ticks, and progress ring\n  - **glass**: glassmorphism panel with accent color bar, progress line, and timestamp\n  - **sakura**: zen garden with bonsai tree and animated cherry blossom petals\n- **categories**: Toggle individual CESP sound categories on\u002Foff (e.g. `\"session.start\": false` to disable greeting sounds)\n- **annoyed_threshold \u002F annoyed_window_seconds**: How many prompts in N seconds triggers the `user.spam` easter egg\n- **silent_window_seconds**: Suppress `task.complete` sounds and notifications for tasks shorter than N seconds. (e.g. `10` to only hear sounds for tasks that take longer than 10 seconds)\n- **session_start_cooldown_seconds** (number, default: `30`): Deduplicates greeting sounds when multiple workspaces start at the same time (e.g. opening OpenCode or Cursor with many folders). Only the first session start plays the greeting; subsequent ones within this window stay silent. Set to `0` to disable deduplication and always play a greeting.\n- **suppress_subagent_complete** (boolean, default: `false`): Suppress `task.complete` sounds and notifications when a sub-agent session finishes. When Claude Code's Task tool dispatches parallel sub-agents, each one fires a completion sound — set this to `true` to hear only the parent session's completion sound.\n- **default_pack**: The fallback pack used when no more specific rule applies (default: `\"peon\"`). Replaces the old `active_pack` key — existing configs are migrated automatically on `peon update`.\n- **path_rules**: Array of `{ \"pattern\": \"...\", \"pack\": \"...\" }` objects. Assigns a pack to sessions based on the working directory using glob matching (`*`, `?`). First matching rule wins. Beats `pack_rotation` and `default_pack`; overridden by `session_override` assignments.\n  ```json\n  \"path_rules\": [\n    { \"pattern\": \"*\u002Fwork\u002Fclient-a\u002F*\", \"pack\": \"glados\" },\n    { \"pattern\": \"*\u002Fpersonal\u002F*\",      \"pack\": \"peon\" }\n  ]\n  ```\n- **pack_rotation**: Array of pack names (e.g. `[\"peon\", \"sc_kerrigan\", \"peasant\"]`). Used when `pack_rotation_mode` is `random` or `round-robin`. Leave empty `[]` to use `default_pack` (or `path_rules`) only.\n- **pack_rotation_mode**: `\"random\"` (default), `\"round-robin\"`, or `\"session_override\"`. With `random`\u002F`round-robin`, each session picks one pack from `pack_rotation`. With `session_override`, the `\u002Fpeon-ping-use \u003Cpack>` command assigns a pack per session. Invalid or missing packs fall back through the hierarchy. (`\"agentskill\"` is accepted as a legacy alias for `\"session_override\"`.)\n- **session_ttl_days** (number, default: 7): Expire stale per-session pack assignments older than N days. Keeps `.state.json` from growing unbounded when using `session_override` mode.\n- **headphones_only** (boolean, default: `false`): Only play sounds when headphones or external audio devices are detected. When enabled, sounds are suppressed if built-in speakers are the active output — useful for open offices. Check status with `peon status`. Supported on macOS (via `system_profiler`) and Linux (via PipeWire `wpctl` or PulseAudio `pactl`).\n- **suppress_sound_when_tab_focused** (boolean, default: `false`): Skip sound playback when the terminal tab that generated the hook event is the currently active\u002Ffocused tab. Sounds still play for background tabs as an alert that something happened elsewhere. Desktop and mobile notifications are unaffected. Useful when you only want audio cues from tabs you're not watching. macOS only (uses `osascript` to check frontmost app and iTerm2 tab focus).\n- **meeting_detect** Detects if the microphone is currently being used and temporarily suppresses the audio only until the microphone is no longer in use. Notification still appears.\n- **notification_position** (string, default: `\"top-center\"`): Where overlay notifications appear on screen. Options: `\"top-left\"`, `\"top-center\"`, `\"top-right\"`, `\"bottom-left\"`, `\"bottom-center\"`, `\"bottom-right\"`.\n- **notification_dismiss_seconds** (number, default: `4`): Auto-dismiss overlay notifications after N seconds. Set to `0` for persistent notifications that require a click to dismiss.\n- **notification_all_screens** (boolean, default: `true`): Show overlay notifications on all screens (`true`) or only the main screen (`false`). Themed overlays (`glass`, `jarvis`, `sakura`) previously only showed on one screen — existing configs with those themes are migrated to `false` automatically. macOS only.\n- **`CLAUDE_SESSION_NAME` env var**: Set before launching `claude` to give a session a custom name. Shows in both desktop notification titles and terminal tab titles. Priority over all config-based naming. Example: `CLAUDE_SESSION_NAME=\"Auth Refactor\" claude` or `export CLAUDE_SESSION_NAME=\"Feature: Auth\"` then `claude`. Each terminal gets its own title automatically since peon-ping runs as a child of that Claude instance.\n- **notification_title_override** (string, default: `\"\"`): Override the project name shown in notification titles. When empty, the project name is auto-detected from `\u002Fpeon-ping-rename` > `CLAUDE_SESSION_NAME` > `.peon-label` > `notification_title_script` > `project_name_map` > git repo name > folder name.\n- **notification_title_script** (string, default: `\"\"`): Shell command run at event time to compute the project name dynamically. Receives env vars: `PEON_SESSION_ID`, `PEON_CWD`, `PEON_HOOK_EVENT`, `PEON_SESSION_NAME`. Use stdout (trimmed, max 50 chars); non-zero exit falls through to the next tier. Example: `\"basename $PEON_CWD\"`.\n- **project_name_map** (object, default: `{}`): Map directory paths to custom project labels for notifications. Keys are path patterns, values are display names. Example: `{ \"\u002Fhome\u002Fuser\u002Fwork\u002Fclient-a\": \"Client A\" }`.\n- **notification_templates** (object, default: `{}`): Custom message format strings for notification events. Keys are event types (`stop`, `permission`, `error`, `idle`, `question`), values are template strings with variable substitution. Available variables: `{project}`, `{summary}`, `{tool_name}`, `{status}`, `{event}`. Example: `{ \"stop\": \"{project}: {summary}\", \"permission\": \"{project}: {tool_name} needs approval\" }`.\n\n### Pack Selection Hierarchy\n\npeon-ping resolves which sound pack to use through a 5-layer hierarchy. The first layer that produces a valid, installed pack wins:\n\n| Priority | Layer | Source | How to set |\n|----------|-------|--------|------------|\n| 1 (highest) | **session_override** | Per-session assignment | `\u002Fpeon-ping-use \u003Cpack>` skill or MCP |\n| 2 | **path_rules** | Glob match on working directory | `peon packs bind` or `path_rules` in config |\n| 3 | **pack_rotation** | Random or round-robin from a list | `pack_rotation` array + `pack_rotation_mode` in config |\n| 4 | **default_pack** | Static fallback | `peon packs use \u003Cname>` or `default_pack` in config |\n| 5 (lowest) | **hardcoded** | Built-in default | `\"peon\"` |\n\nIf a layer references a pack that is not installed, it falls through to the next layer.\n\n### Per-Project Pack Assignment (path_rules)\n\nAssign different sound packs to different projects based on directory path. Use the CLI or edit `config.json` directly.\n\n**CLI (recommended):**\n\n```bash\npeon packs bind glados                     # Bind glados to the current directory\npeon packs bind sc_kerrigan --pattern \"*\u002Fservices\u002F*\"  # Bind to a glob pattern\npeon packs bind duke_nukem --install       # Bind and install from registry if needed\npeon packs unbind                          # Remove binding for the current directory\npeon packs unbind --pattern \"*\u002Fservices\u002F*\" # Remove a specific pattern binding\npeon packs bindings                        # List all bindings\n```\n\n**Manual config:**\n\n```json\n\"path_rules\": [\n  { \"pattern\": \"*\u002Fwork\u002Fclient-a\u002F*\", \"pack\": \"glados\" },\n  { \"pattern\": \"*\u002Fpersonal\u002F*\",      \"pack\": \"peon\" },\n  { \"pattern\": \"*\u002Fservices\u002F*\",      \"pack\": \"sc_kerrigan\" }\n]\n```\n\nRules use glob matching (`*`, `?`). First matching rule wins. Path rules override `pack_rotation` and `default_pack` but are overridden by `session_override` assignments.\n\n## Common Use Cases\n\n### Sounds without popups\n\nWant voice feedback but no visual distractions?\n\n```bash\npeon notifications off\n```\n\nThis keeps all sound categories playing while suppressing desktop notification banners. Mobile notifications (if configured) continue working.\n\nYou can also use the alias:\n\n```bash\npeon popups off\n```\n\n### Silent mode with notifications only\n\nWant visual alerts but no audio?\n\n```bash\npeon pause  # or set \"enabled\": false in config\n```\n\nWith `desktop_notifications: true`, you'll get popups but no sounds.\n\n### Complete silence\n\nDisable everything:\n\n```bash\npeon pause\npeon notifications off\npeon mobile off\n```\n\n## Peon Trainer\n\nYour peon is also your personal trainer. Built-in Pavel-style daily exercise mode — the same orc who tells you \"work work\" now tells you to drop and give him twenty.\n\n### Quick start\n\n```bash\npeon trainer on              # enable trainer\npeon trainer goal 200        # set daily goal (default: 300\u002F300)\n# ... code for a while, peon nags you every ~20 min ...\npeon trainer log 25 pushups  # log what you did\npeon trainer log 30 squats\npeon trainer status          # check progress\n```\n\n### How it works\n\nTrainer reminders piggyback on your coding session. When you start a new session, the peon immediately encourages you to start strong with pushups before you write any code. Then every ~20 minutes of active coding, you'll hear the peon yelling at you to do more reps. No background daemon needed. Log your reps with `peon trainer log`, and progress resets automatically at midnight.\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `peon trainer on` | Enable trainer mode |\n| `peon trainer off` | Disable trainer mode |\n| `peon trainer status` | Show today's progress |\n| `peon trainer log \u003Cn> \u003Cexercise>` | Log reps (e.g. `log 25 pushups`) |\n| `peon trainer goal \u003Cn>` | Set goal for all exercises |\n| `peon trainer goal \u003Cexercise> \u003Cn>` | Set goal for one exercise |\n\n### Claude Code skill\n\nIn Claude Code, you can log reps without leaving your conversation:\n\n```\n\u002Fpeon-ping-log 25 pushups\n\u002Fpeon-ping-log 30 squats\n```\n\n### Custom voice lines\n\nDrop your own audio files into `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Ftrainer\u002Fsounds\u002F`:\n\n```\ntrainer\u002Fsounds\u002Fsession_start\u002F  # session greeting (\"Pushups first, code second! Zug zug!\")\ntrainer\u002Fsounds\u002Fremind\u002F         # reminder lines (\"Something need doing? YES. PUSHUPS.\")\ntrainer\u002Fsounds\u002Flog\u002F            # acknowledgment (\"Work work! Muscles getting bigger maybe!\")\ntrainer\u002Fsounds\u002Fcomplete\u002F       # celebration (\"Zug zug! Human finish all reps!\")\ntrainer\u002Fsounds\u002Fslacking\u002F       # disappointment (\"Peon very disappointed.\")\n```\n\nUpdate `trainer\u002Fmanifest.json` to register your sound files.\n\n## MCP server\n\npeon-ping includes an [MCP (Model Context Protocol)](https:\u002F\u002Fmodelcontextprotocol.io\u002F) server so any MCP-compatible AI agent can play sounds directly via tool calls — no hooks required.\n\nThe key difference: **the agent chooses the sound**. Instead of automatically playing a fixed sound on every event, the agent calls `play_sound` with exactly what it wants — `duke_nukem\u002FSonOfABitch` when a build fails, `sc_kerrigan\u002FIReadYou` when reading files.\n\n### Setup\n\nAdd to your MCP client config (Claude Desktop, Cursor, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"peon-ping\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fpath\u002Fto\u002Fpeon-ping\u002Fmcp\u002Fpeon-mcp.js\"]\n    }\n  }\n}\n```\n\nIf installed via Homebrew: `$(brew --prefix peon-ping)\u002Flibexec\u002Fmcp\u002Fpeon-mcp.js`. See [`mcp\u002FREADME.md`](mcp\u002FREADME.md) for full setup instructions.\n\n### What the agent can do\n\n| Feature | Description |\n|---|---|\n| **`play_sound`** | Play one or more sounds by key (e.g. `duke_nukem\u002FSonOfABitch`, `peon\u002FPeonReady1`) |\n| **`peon-ping:\u002F\u002Fcatalog`** | Full pack catalog as an MCP Resource — client prefetches once, no repeated tool calls |\n| **`peon-ping:\u002F\u002Fpack\u002F{name}`** | Individual pack details and available sound keys |\n\nRequires Node.js 18+. Contributed by [@tag-assistant](https:\u002F\u002Fgithub.com\u002Ftag-assistant).\n\n## Multi-IDE Support\n\npeon-ping works with any agentic IDE that supports hooks. Adapters translate IDE-specific events to the [CESP standard](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon).\n\n| IDE | Status | Setup |\n|---|---|---|\n| **Claude Code** | Built-in | `curl \\| bash` install handles everything |\n| **Amp** | Adapter | `bash adapters\u002Famp.sh` \u002F `powershell adapters\u002Famp.ps1` ([setup](#amp-setup)) |\n| **Gemini CLI** | Adapter | Add hooks pointing to `adapters\u002Fgemini.sh` (or `.ps1` on Windows) ([setup](#gemini-cli-setup)) |\n| **GitHub Copilot** | Adapter | Add hooks to `.github\u002Fhooks\u002Fhooks.json` pointing to `adapters\u002Fcopilot.sh` (or `.ps1`) ([setup](#github-copilot-setup)) |\n| **OpenAI Codex** | Adapter | Install the peon-ping runtime first, then add `notify` in `~\u002F.codex\u002Fconfig.toml` pointing to `adapters\u002Fcodex.sh` (or `.ps1`) ([setup](#openai-codex-setup)) |\n| **Cursor** | Built-in | `curl \\| bash`, `peon-ping-setup`, or Windows `install.ps1` auto-detect and register hooks. On Windows, enable **Settings → Features → Third-party skills** so Cursor loads `~\u002F.claude\u002Fsettings.json` for SessionStart\u002FStop sounds. |\n| **OpenCode** | Adapter | `bash adapters\u002Fopencode.sh` \u002F `powershell adapters\u002Fopencode.ps1` ([setup](#opencode-setup)) |\n| **Kilo CLI** | Adapter | `bash adapters\u002Fkilo.sh` \u002F `powershell adapters\u002Fkilo.ps1` ([setup](#kilo-cli-setup)) |\n| **Kiro** | Adapter | Add hook entries pointing to `adapters\u002Fkiro.sh` (or `.ps1`) ([setup](#kiro-setup)) |\n| **Windsurf** | Adapter | Add hook entries pointing to `adapters\u002Fwindsurf.sh` (or `.ps1`) ([setup](#windsurf-setup)) |\n| **Google Antigravity** | Adapter | `bash adapters\u002Fantigravity.sh` \u002F `powershell adapters\u002Fantigravity.ps1` |\n| **Kimi Code** | Adapter | `bash adapters\u002Fkimi.sh --install` \u002F `powershell adapters\u002Fkimi.ps1 -Install` ([setup](#kimi-code-setup)) |\n| **OpenClaw** | Adapter | Call `adapters\u002Fopenclaw.sh \u003Cevent>` (or `openclaw.ps1`) from your OpenClaw skill |\n| **Rovo Dev CLI** | Adapter | Auto-registered by `install.sh` if `~\u002F.rovodev` exists, or add hooks to `~\u002F.rovodev\u002Fconfig.yml` manually ([setup](#rovo-dev-cli-setup)) |\n| **DeepAgents** | Adapter | `bash adapters\u002Fdeepagents.sh` \u002F `powershell adapters\u002Fdeepagents.ps1` ([setup](#deepagents-setup)) |\n\n> **Windows:** All adapters have native PowerShell (`.ps1`) versions. The Windows installer (`install.ps1`) copies them to `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002F`. Filesystem watchers (Amp, Antigravity, Kimi) use .NET `FileSystemWatcher` instead of fswatch\u002Finotifywait — no extra dependencies needed.\n\n### OpenAI Codex setup\n\nCodex support uses an adapter and is not auto-registered by `peon-ping-setup`.\n\nThe Codex adapter expects the peon-ping runtime to exist at `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002F`, even if you only use Codex and do not use Claude Code.\n\n**Setup:**\n\n1. Install the peon-ping runtime first:\n\n   ```bash\n   bash \"$(brew --prefix peon-ping)\"\u002Flibexec\u002Finstall.sh --no-rc\n   ```\n\n   Or with the standard installer:\n\n   ```bash\n   curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.sh | bash -s -- --no-rc\n   ```\n\n2. Add this to `~\u002F.codex\u002Fconfig.toml`:\n\n   ```toml\n   notify = [\"bash\", \"~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fcodex.sh\"]\n   ```\n\n3. Restart Codex.\n\nIf you installed with Homebrew, the runtime files are managed under `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002F`, and the Codex adapter forwards Codex notify events into that shared runtime.\n\n### Amp setup\n\nA filesystem watcher adapter for [Amp](https:\u002F\u002Fampcode.com) (by Sourcegraph). Amp doesn't expose event hooks like Claude Code, so this adapter watches Amp's thread files on disk and detects when the agent finishes a turn.\n\n**Setup:**\n\n1. Ensure peon-ping is installed (`curl -fsSL https:\u002F\u002Fpeonping.com\u002Finstall | bash`)\n\n2. Install `fswatch` (macOS) or `inotify-tools` (Linux):\n\n   ```bash\n   brew install fswatch        # macOS\n   sudo apt install inotify-tools  # Linux\n   ```\n\n3. Start the watcher:\n\n   ```bash\n   bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Famp.sh        # foreground\n   bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Famp.sh &       # background\n   ```\n\n**Event mapping:**\n\n- New thread file created → Greeting sound (*\"Ready to work?\"*, *\"Yes?\"*)\n- Thread file stops updating + agent finished turn → Completion sound (*\"Work, work.\"*, *\"Job's done!\"*)\n\n**How it works:**\n\nThe adapter watches `~\u002F.local\u002Fshare\u002Famp\u002Fthreads\u002F` for JSON file changes. When a thread file stops updating (1s idle timeout) and the last message is from the assistant with text content (not a pending tool call), it emits a `Stop` event — meaning the agent is done and waiting for your input.\n\n**Environment variables:**\n\n| Variable | Default | Description |\n|---|---|---|\n| `AMP_DATA_DIR` | `~\u002F.local\u002Fshare\u002Famp` | Amp data directory |\n| `AMP_THREADS_DIR` | `$AMP_DATA_DIR\u002Fthreads` | Threads directory to watch |\n| `AMP_IDLE_SECONDS` | `1` | Seconds of no changes before emitting Stop |\n| `AMP_STOP_COOLDOWN` | `10` | Minimum seconds between Stop events per thread |\n\n### GitHub Copilot setup\n\nA shell adapter for [GitHub Copilot](https:\u002F\u002Fgithub.com\u002Ffeatures\u002Fcopilot) with full [CESP v1.0](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) conformance.\n\n**Setup:**\n\n1. Ensure peon-ping is installed (`curl -fsSL https:\u002F\u002Fpeonping.com\u002Finstall | bash`)\n\n2. Create `.github\u002Fhooks\u002Fhooks.json` in your repository (on the default branch):\n\n   ```json\n   {\n     \"version\": 1,\n     \"hooks\": {\n       \"sessionStart\": [\n         {\n           \"type\": \"command\",\n           \"bash\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fcopilot.sh sessionStart\"\n         }\n       ],\n       \"userPromptSubmitted\": [\n         {\n           \"type\": \"command\",\n           \"bash\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fcopilot.sh userPromptSubmitted\"\n         }\n       ],\n       \"postToolUse\": [\n         {\n           \"type\": \"command\",\n           \"bash\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fcopilot.sh postToolUse\"\n         }\n       ],\n       \"errorOccurred\": [\n         {\n           \"type\": \"command\",\n           \"bash\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fcopilot.sh errorOccurred\"\n         }\n       ]\n     }\n   }\n   ```\n\n3. Commit and merge to your default branch. Hooks will activate on your next Copilot agent session.\n\n**Event mapping:**\n\n- `sessionStart` → Greeting sound (*\"Ready to work?\"*, *\"Yes?\"*)\n- `userPromptSubmitted` → First prompt = greeting, subsequent = spam detection\n- `postToolUse` → Completion sound (*\"Work, work.\"*, *\"Job's done!\"*)\n- `errorOccurred` → Error sound (*\"I can't do that.\"*)\n- `preToolUse` → Skipped (too noisy)\n- `sessionEnd` → No sound (session.end not yet implemented)\n\n**Features:**\n\n- **Sound playback** via `afplay` (macOS), `pw-play`\u002F`paplay`\u002F`ffplay` (Linux) — same priority chain as the shell hook\n- **CESP event mapping** — GitHub Copilot hooks map to standard CESP categories (`session.start`, `task.complete`, `task.error`, `user.spam`)\n- **Desktop notifications** — large overlay banners by default, or standard notifications\n- **Spam detection** — detects 3+ rapid prompts within 10 seconds, triggers `user.spam` voice lines\n- **Session tracking** — separate session markers per Copilot sessionId\n\n### OpenCode setup\n\nA native TypeScript plugin for [OpenCode](https:\u002F\u002Fopencode.ai\u002F) with full [CESP v1.0](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) conformance.\n\n**Quick install:**\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Fadapters\u002Fopencode.sh | bash\n```\n\nThe installer copies `peon-ping.ts` to `~\u002F.config\u002Fopencode\u002Fplugins\u002F` and creates a config at `~\u002F.config\u002Fopencode\u002Fpeon-ping\u002Fconfig.json`. Packs are stored at the shared CESP path (`~\u002F.openpeon\u002Fpacks\u002F`).\n\n**Features:**\n\n- **Sound playback** via `afplay` (macOS), `pw-play`\u002F`paplay`\u002F`ffplay` (Linux) — same priority chain as the shell hook\n- **CESP event mapping** — `session.created` \u002F `session.idle` \u002F `session.error` \u002F `permission.asked` \u002F rapid prompt detection all map to standard CESP categories\n- **Desktop notifications** — large overlay banners by default (JXA Cocoa, visible on all screens), or standard notifications via [`terminal-notifier`](https:\u002F\u002Fgithub.com\u002FjulienXX\u002Fterminal-notifier) \u002F `osascript`. Fires only when the terminal is not focused.\n- **Terminal focus detection** — checks if your terminal app (Terminal, iTerm2, Warp, Alacritty, kitty, WezTerm, ghostty, Hyper) is frontmost via AppleScript before sending notifications\n- **Tab titles** — updates the terminal tab to show task status (`● project: working...` \u002F `✓ project: done` \u002F `✗ project: error`)\n- **Pack switching** — reads `default_pack` from config (with `active_pack` fallback for legacy configs), loads the pack's `openpeon.json` manifest at runtime. `path_rules` can override the pack per working directory.\n- **No-repeat logic** — avoids playing the same sound twice in a row per category\n- **Spam detection** — detects 3+ rapid prompts within 10 seconds, triggers `user.spam` voice lines\n\n\u003Cdetails>\n\u003Csummary>🖼️ Screenshot: desktop notifications with custom peon icon\u003C\u002Fsummary>\n\n![peon-ping OpenCode notifications](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FPeonPing_peon-ping_readme_cecac425801f.png)\n\n\u003C\u002Fdetails>\n\n> **Tip:** Install `terminal-notifier` (`brew install terminal-notifier`) for richer notifications with subtitle and grouping support.\n\n\u003Cdetails>\n\u003Csummary>🎨 Optional: custom peon icon for notifications\u003C\u002Fsummary>\n\nBy default, `terminal-notifier` shows a generic Terminal icon. The included script replaces it with the peon icon using built-in macOS tools (`sips` + `iconutil`) — no extra dependencies.\n\n```bash\nbash \u003C(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Fadapters\u002Fopencode\u002Fsetup-icon.sh)\n```\n\nOr if installed locally (Homebrew \u002F git clone):\n\n```bash\nbash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fopencode\u002Fsetup-icon.sh\n```\n\nThe script auto-finds the peon icon (Homebrew libexec, OpenCode config, or Claude hooks dir), generates a proper `.icns`, backs up the original `Terminal.icns`, and replaces it. Re-run after `brew upgrade terminal-notifier`.\n\n> **Future:** When [jamf\u002FNotifier](https:\u002F\u002Fgithub.com\u002Fjamf\u002FNotifier) ships to Homebrew ([#32](https:\u002F\u002Fgithub.com\u002Fjamf\u002FNotifier\u002Fissues\u002F32)), the plugin will migrate to it — Notifier has built-in `--rebrand` support, no icon hacks needed.\n\n\u003C\u002Fdetails>\n\n### Kilo CLI setup\n\nA native TypeScript plugin for [Kilo CLI](https:\u002F\u002Fgithub.com\u002Fkilocode\u002Fcli) with full [CESP v1.0](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) conformance. Kilo CLI is a fork of OpenCode and uses the same plugin system — this installer downloads the OpenCode plugin and patches it for Kilo.\n\n**Quick install:**\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Fadapters\u002Fkilo.sh | bash\n```\n\nThe installer copies `peon-ping.ts` to `~\u002F.config\u002Fkilo\u002Fplugins\u002F` and creates a config at `~\u002F.config\u002Fkilo\u002Fpeon-ping\u002Fconfig.json`. Packs are stored at the shared CESP path (`~\u002F.openpeon\u002Fpacks\u002F`).\n\n**Features:** Same as the [OpenCode adapter](#opencode-setup) — sound playback, CESP event mapping, desktop notifications, terminal focus detection, tab titles, pack switching, no-repeat logic, and spam detection.\n\n### Gemini CLI setup\n\nA shell adapter for **Gemini CLI** with full [CESP v1.0](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) conformance.\n\n**Setup:**\n\n1. Ensure peon-ping is installed (`curl -fsSL https:\u002F\u002Fpeonping.com\u002Finstall | bash`)\n\n2. Add the following hooks to your `~\u002F.gemini\u002Fsettings.json`:\n\n   ```json\n    {\n      \"hooks\": {\n        \"SessionStart\": [\n          {\n            \"matcher\": \"startup\",\n            \"hooks\": [\n              {\n                \"name\": \"peon-start\",\n                \"type\": \"command\",\n                \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fgemini.sh SessionStart\"\n              }\n            ]\n          }\n        ],\n        \"AfterAgent\": [\n          {\n            \"matcher\": \"*\",\n            \"hooks\": [\n              {\n                \"name\": \"peon-after-agent\",\n                \"type\": \"command\",\n                \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fgemini.sh AfterAgent\"\n              }\n            ]\n          }\n        ],\n        \"AfterTool\": [\n          {\n            \"matcher\": \"*\",\n            \"hooks\": [\n              {\n                \"name\": \"peon-after-tool\",\n                \"type\": \"command\",\n                \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fgemini.sh AfterTool\"\n              }\n            ]\n          }\n        ],\n        \"Notification\": [\n          {\n            \"matcher\": \"*\",\n            \"hooks\": [\n              {\n                \"name\": \"peon-notification\",\n                \"type\": \"command\",\n                \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fgemini.sh Notification\"\n              }\n            ]\n          }\n        ]\n      }\n    }\n   ```\n\n**Event mapping:**\n\n- `SessionStart` (startup) → Greeting sound (*\"Ready to work?\"*, *\"Yes?\"*)\n- `AfterAgent` → Task completion sound (*\"Work, work.\"*, *\"Job's done!\"*)\n- `AfterTool` → Success = Task completion sound, Failure = Error sound (*\"I can't do that.\"*)\n- `Notification` → System notification\n\n### Windsurf setup\n\nAdd to `~\u002F.codeium\u002Fwindsurf\u002Fhooks.json` (user-level) or `.windsurf\u002Fhooks.json` (workspace-level):\n\n```json\n{\n  \"hooks\": {\n    \"post_cascade_response\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fwindsurf.sh post_cascade_response\", \"show_output\": false }\n    ],\n    \"pre_user_prompt\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fwindsurf.sh pre_user_prompt\", \"show_output\": false }\n    ],\n    \"post_write_code\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fwindsurf.sh post_write_code\", \"show_output\": false }\n    ],\n    \"post_run_command\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fwindsurf.sh post_run_command\", \"show_output\": false }\n    ]\n  }\n}\n```\n\n### Kiro setup\n\nCreate `~\u002F.kiro\u002Fagents\u002Fpeon-ping.json`:\n\n```json\n{\n  \"name\": \"peon-ping\",\n  \"hooks\": {\n    \"agentSpawn\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkiro.sh\" }\n    ],\n    \"userPromptSubmit\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkiro.sh\" }\n    ],\n    \"stop\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkiro.sh\" }\n    ]\n  }\n}\n```\n\n`preToolUse`\u002F`postToolUse` are intentionally excluded — they fire on every tool call and would be extremely noisy.\n\n### Rovo Dev CLI setup\n\nA shell adapter for [Rovo Dev CLI](https:\u002F\u002Fdeveloper.atlassian.com\u002Fcloud\u002Frovo\u002F) (Atlassian) with full [CESP v1.0](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) conformance.\n\n**Auto-setup:**\n\nIf `~\u002F.rovodev\u002Fconfig.yml` exists when you run `install.sh` or `peon-ping-setup`, event hooks are registered automatically.\n\n**Manual setup:**\n\n1. Ensure peon-ping is installed (`curl -fsSL https:\u002F\u002Fpeonping.com\u002Finstall | bash`)\n\n2. Add to `~\u002F.rovodev\u002Fconfig.yml`:\n\n   ```yaml\n   eventHooks:\n     events:\n       - name: on_complete\n         commands:\n           - command: bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Frovodev.sh on_complete\n       - name: on_error\n         commands:\n           - command: bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Frovodev.sh on_error\n       - name: on_tool_permission\n         commands:\n           - command: bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Frovodev.sh on_tool_permission\n   ```\n\n3. Restart Rovo Dev CLI for the hooks to take effect.\n\n**Event mapping:**\n\n- `on_complete` → Completion sound (*\"Work, work.\"*, *\"Job's done!\"*)\n- `on_error` → Error sound (*\"I can't do that.\"*, *\"Son of a bitch!\"*)\n- `on_tool_permission` → Permission prompt sound (*\"Something need doing?\"*, *\"Hmm?\"*)\n\n**Features:**\n\n- **Sound playback** via `afplay` (macOS), `pw-play`\u002F`paplay`\u002F`ffplay` (Linux) — same priority chain as the shell hook\n- **CESP event mapping** — Rovo Dev events map to standard CESP categories (`task.complete`, `task.error`, `input.required`)\n- **Desktop notifications** — large overlay banners by default, or standard notifications\n- **Debounce** — suppresses duplicate sounds from rapid completions\n\n### Kimi Code setup\n\nA filesystem watcher adapter for [Kimi Code CLI](https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-cli) (MoonshotAI). Kimi Code writes Wire Mode events to `~\u002F.kimi\u002Fsessions\u002F` — this adapter watches those files as a background daemon and translates events to CESP format.\n\n```bash\n# Install (starts background daemon)\nbash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkimi.sh --install\n\n# Check status \u002F stop\nbash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkimi.sh --status\nbash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkimi.sh --uninstall\n```\n\nRequires `fswatch` (`brew install fswatch`) on macOS or `inotifywait` (`apt install inotify-tools`) on Linux. The `curl | bash` installer auto-detects Kimi Code and starts the daemon.\n\n**Event mapping:**\n\n- New session → Greeting sound (*\"Ready to work?\"*, *\"Yes?\"*)\n- Agent finishes turn → Completion sound (*\"Work, work.\"*, *\"Job's done!\"*)\n- Context compaction → Token limit sound\n- Sub-agent spawned → Sub-agent tracking\n\n## Remote development (SSH \u002F Devcontainers \u002F Codespaces)\n\nCoding on a remote server or inside a container? peon-ping auto-detects SSH sessions, devcontainers, and Codespaces, then routes audio and notifications through a lightweight relay running on your local machine.\n\n### SSH setup\n\n1. **On your local machine**, start the relay:\n   ```bash\n   peon relay --daemon\n   ```\n\n2. **SSH with port forwarding**:\n   ```bash\n   ssh -R 19998:localhost:19998 your-server\n   ```\n\n3. **Install peon-ping on the remote** — it auto-detects the SSH session and sends audio requests back through the forwarded port to your local relay.\n\nThat's it. Sounds play on your laptop, not the remote server.\n\nOptional SSH routing modes:\n\n```bash\npeon ssh-audio relay   # default, always use relay\npeon ssh-audio auto    # try relay, fall back to local playback on SSH host\npeon ssh-audio local   # always play on SSH host\n```\n\n### Devcontainers \u002F Codespaces\n\nNo port forwarding needed — peon-ping auto-detects `REMOTE_CONTAINERS` and `CODESPACES` environment variables and routes audio to `host.docker.internal:19998`. Just run `peon relay --daemon` on your host machine.\n\n### Relay commands\n\n```bash\npeon relay                # Start relay in foreground\npeon relay --daemon       # Start in background\npeon relay --stop         # Stop background relay\npeon relay --status       # Check if relay is running\npeon relay --port=12345   # Custom port (default: 19998)\npeon relay --bind=0.0.0.0 # Listen on all interfaces (less secure)\n```\n\nEnvironment variables: `PEON_RELAY_PORT`, `PEON_RELAY_HOST`, `PEON_RELAY_BIND`.\n\nIf peon-ping detects an SSH or container session but can't reach the relay, it prints setup instructions on `SessionStart`.\n\n### Category-based API (for lightweight remote hooks)\n\nThe relay supports a category-based endpoint that handles sound selection server-side. This is useful for remote machines where peon-ping isn't installed — the remote hook only needs to send a category name, and the relay picks a random sound from the active pack.\n\n**Endpoints:**\n\n| Endpoint | Description |\n|---|---|\n| `GET \u002Fhealth` | Health check (returns \"OK\") |\n| `GET \u002Fplay?file=\u003Cpath>` | Play a specific sound file (legacy) |\n| `GET \u002Fplay?category=\u003Ccat>` | Play random sound from category (recommended) |\n| `POST \u002Fnotify` | Send desktop notification |\n\n**Example remote hook (`scripts\u002Fremote-hook.sh`):**\n\n```bash\n#!\u002Fbin\u002Fbash\nRELAY_URL=\"${PEON_RELAY_URL:-http:\u002F\u002F127.0.0.1:19998}\"\nEVENT=$(cat | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get('hook_event_name',''))\" 2>\u002Fdev\u002Fnull)\ncase \"$EVENT\" in\n  SessionStart)      CATEGORY=\"session.start\" ;;\n  Stop)              CATEGORY=\"task.complete\" ;;\n  PermissionRequest) CATEGORY=\"input.required\" ;;\n  *)                 exit 0 ;;\nesac\ncurl -sf \"${RELAY_URL}\u002Fplay?category=${CATEGORY}\" >\u002Fdev\u002Fnull 2>&1 &\n```\n\nCopy this to your remote machine and register it in `~\u002F.claude\u002Fsettings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [{\"command\": \"bash \u002Fpath\u002Fto\u002Fremote-hook.sh\"}],\n    \"Stop\": [{\"command\": \"bash \u002Fpath\u002Fto\u002Fremote-hook.sh\"}],\n    \"PermissionRequest\": [{\"command\": \"bash \u002Fpath\u002Fto\u002Fremote-hook.sh\"}]\n  }\n}\n```\n\nThe relay reads `config.json` on your local machine to get the active pack and volume, loads the pack's manifest, and picks a random sound while avoiding repeats.\n\n## Mobile notifications\n\nGet push notifications on your phone when tasks finish or need attention — useful when you're away from your desk.\n\n### Quick start (ntfy.sh — free, no account needed)\n\n1. Install the [ntfy app](https:\u002F\u002Fntfy.sh) on your phone\n2. Subscribe to a unique topic in the app (e.g. `my-peon-notifications`)\n3. Run:\n   ```bash\n   peon mobile ntfy my-peon-notifications\n   ```\n\nAlso supports [Pushover](https:\u002F\u002Fpushover.net) and [Telegram](https:\u002F\u002Fcore.telegram.org\u002Fbots):\n\n```bash\npeon mobile pushover \u003Cuser_key> \u003Capp_token>\npeon mobile telegram \u003Cbot_token> \u003Cchat_id>\n```\n\n### Mobile commands\n\n```bash\npeon mobile on            # Enable mobile notifications\npeon mobile off           # Disable mobile notifications\npeon mobile status        # Show current config\npeon mobile test          # Send a test notification\n```\n\nMobile notifications fire on every event regardless of window focus — they're independent from desktop notifications and sounds.\n\n## Sound packs\n\n165 packs across Warcraft, StarCraft, Red Alert, Portal, Zelda, Dota 2, Helldivers 2, Elder Scrolls, and more. The default install includes 5 curated packs:\n\n| Pack | Character | Sounds |\n|---|---|---|\n| `peon` (default) | Orc Peon (Warcraft III) | \"Ready to work?\", \"Work, work.\", \"Okie dokie.\" |\n| `peasant` | Human Peasant (Warcraft III) | \"Yes, milord?\", \"Job's done!\", \"Ready, sir.\" |\n| `sc_kerrigan` | Sarah Kerrigan (StarCraft) | \"I gotcha\", \"What now?\", \"Easily amused, huh?\" |\n| `sc_battlecruiser` | Battlecruiser (StarCraft) | \"Battlecruiser operational\", \"Make it happen\", \"Engage\" |\n| `glados` | GLaDOS (Portal) | \"Oh, it's you.\", \"You monster.\", \"Your entire team is dead.\" |\n\n**[Browse all packs with audio previews → openpeon.com\u002Fpacks](https:\u002F\u002Fopenpeon.com\u002Fpacks)**\n\nInstall all with `--all`, or switch packs anytime:\n\n```bash\npeon packs use glados             # switch to a specific pack\npeon packs use --install glados   # install (or update) and switch in one step\npeon packs next                   # cycle to the next pack\npeon packs list                   # list all installed packs\npeon packs list --registry        # browse all available packs\npeon packs install glados,murloc  # install specific packs\npeon packs install --all          # install every pack in the registry\n```\n\nWant to add your own pack? See the [full guide at openpeon.com\u002Fcreate](https:\u002F\u002Fopenpeon.com\u002Fcreate) or [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Debugging\n\nWhen sounds aren't playing or notifications aren't appearing, structured debug logging helps you trace exactly what happened during a hook invocation.\n\n### Enabling debug logs\n\n```bash\npeon debug on             # Enable — logs written to ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Flogs\u002F\npeon debug off            # Disable\npeon debug status         # Show state, log directory, file count, total size\n```\n\nYou can also enable debug logging per-invocation without changing config by setting the environment variable `PEON_DEBUG=1`.\n\n### Reading logs\n\n```bash\npeon logs                 # Last 50 lines of today's log\npeon logs --last 100      # Last 100 lines across all log files\npeon logs --session \u003CID>  # Filter today's log by session ID\npeon logs --session \u003CID> --all  # Search all log files for session ID\npeon logs --clear         # Delete all log files (with confirmation)\n```\n\n### Log format\n\nEach log line is a structured key=value record:\n\n```\n2026-03-26T14:32:01.042 [config] inv=a3f1 loaded=\u002Fpath\u002Fto\u002Fconfig.json volume=0.5 pack=peon enabled=True\n2026-03-26T14:32:01.045 [event] inv=a3f1 hook_event=Stop cesp=task.complete session=abc123\n2026-03-26T14:32:01.048 [sound] inv=a3f1 file=work-work.wav label=\"Work, work.\" category=task.complete\n2026-03-26T14:32:01.120 [play] inv=a3f1 player=afplay file=work-work.wav\n2026-03-26T14:32:01.125 [notify] inv=a3f1 title=\"peon: done\" body=\"Work, work.\"\n```\n\n- **inv** -- unique 4-character invocation ID linking all phases of a single hook call\n- **Phases**: `[config]`, `[event]`, `[sound]`, `[play]`, `[notify]` -- each represents a stage in the hook pipeline\n- Values containing spaces or special characters are quoted\n\n### Common failure examples\n\n| Symptom | What to look for in logs |\n|---|---|\n| No sound plays | `[event]` line shows `exit=early` (category disabled, paused, or debounced) |\n| Wrong pack | `[config]` line shows unexpected `pack=` value -- check path_rules or rotation |\n| Missing sound file | `[sound]` line shows `error=` with file path |\n| Notification missing | `[notify]` line absent -- check `desktop_notifications` in config |\n\n### Config keys\n\n| Key | Default | Description |\n|---|---|---|\n| `debug` | `false` | Enable structured debug logging |\n| `debug_retention_days` | `7` | Auto-prune logs older than N days |\n\nLogs are stored at `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Flogs\u002Fpeon-ping-YYYY-MM-DD.log` (one file per day). Old logs are automatically pruned based on `debug_retention_days` when a new day's log is created.\n\n## Uninstall\n\n**macOS\u002FLinux:**\n\n```bash\nbash \"${CLAUDE_CONFIG_DIR:-$HOME\u002F.claude}\"\u002Fhooks\u002Fpeon-ping\u002Funinstall.sh        # global\nbash .claude\u002Fhooks\u002Fpeon-ping\u002Funinstall.sh           # project-local\n```\n\n**Windows (PowerShell):**\n\n```powershell\n# Standard uninstall (prompts before deleting sounds)\npowershell -File \"$env:USERPROFILE\\.claude\\hooks\\peon-ping\\uninstall.ps1\"\n\n# Keep sound packs (removes everything else)\npowershell -File \"$env:USERPROFILE\\.claude\\hooks\\peon-ping\\uninstall.ps1\" -KeepSounds\n```\n\n## Requirements\n\n- **macOS** — `afplay` (built-in), JXA Cocoa overlay or AppleScript for notifications\n- **Linux** — one of: `pw-play`, `paplay`, `ffplay`, `mpv`, `play` (SoX), or `aplay`; `notify-send` for notifications\n- **Windows** — native PowerShell with `MediaPlayer` and WinForms (no WSL required), or WSL2\n- **MSYS2 \u002F Git Bash** — `python3`, `cygpath` (built-in); audio via `ffplay`\u002F`mpv`\u002F`play` or PowerShell fallback\n- **All platforms** — `python3` (not required for native Windows)\n- **SSH\u002Fremote** — `curl` on the remote host\n- **IDE** — Claude Code with hooks support, Amp, or any supported IDE via [adapters](#multi-ide-support)\n\n## How it works\n\n`peon.sh` is a Claude Code hook registered for `SessionStart`, `SessionEnd`, `SubagentStart`, `Stop`, `Notification`, `PermissionRequest`, `PostToolUseFailure`, and `PreCompact` events. On each event:\n\n1. **Event mapping** — an embedded Python block maps the hook event to a [CESP](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) sound category (`session.start`, `task.complete`, `input.required`, etc.)\n2. **Sound selection** — picks a random voice line from the active pack's manifest, avoiding repeats\n3. **Audio playback** — plays the sound asynchronously via `afplay` (macOS), PowerShell `MediaPlayer` (WSL2\u002FMSYS2 fallback), or `pw-play`\u002F`paplay`\u002F`ffplay`\u002F`mpv`\u002F`aplay` (Linux\u002FMSYS2)\n4. **Notifications** — updates the Terminal tab title and sends a desktop notification if the terminal isn't focused\n5. **Remote routing** — in SSH sessions, devcontainers, and Codespaces, audio and notification requests are forwarded over HTTP to a [relay server](#remote-development-ssh--devcontainers--codespaces) on your local machine\n\nSound packs are downloaded from the [OpenPeon registry](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fregistry) at install time. The official packs are hosted in [PeonPing\u002Fog-packs](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fog-packs). Sound files are property of their respective publishers (Blizzard, Valve, EA, etc.) and are distributed under fair use for personal notification purposes.\n\n## Links\n\n- [@peonping on X](https:\u002F\u002Fx.com\u002Fpeonping) — updates and announcements\n- [peonping.com](https:\u002F\u002Fpeonping.com\u002F) — landing page\n- [openpeon.com](https:\u002F\u002Fopenpeon.com\u002F) — CESP spec, pack browser, [integration guide](https:\u002F\u002Fopenpeon.com\u002Fintegrate), creation guide\n- [OpenPeon registry](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fregistry) — pack registry (GitHub Pages)\n- [og-packs](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fog-packs) — official sound packs\n- [peon-pet](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-pet) — macOS desktop pet (orc sprite, reacts to hook events)\n- [License (MIT)](LICENSE)\n\n## Support the project\n\n- Venmo: [@garysheng](https:\u002F\u002Fvenmo.com\u002Fgarysheng)\n- Community Token (DYOR \u002F have fun): Someone created a $PEON token on Base — we receive TX fees which help fund development. [`0xf4ba744229afb64e2571eef89aacec2f524e8ba3`](https:\u002F\u002Fdexscreener.com\u002Fbase\u002F0xf4bA744229aFB64E2571eef89AaceC2F524e8bA3)\n","# peon-ping\n\u003Cdiv align=\"center\">\n\n**英语** | [韩语](README_ko.md) | [中文](README_zh.md) | [日语](README_ja.md)\n\n![macOS](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FmacOS-blue) ![WSL2](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FWSL2-blue) ![Linux](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLinux-blue) ![Windows](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FWindows-blue) ![MSYS2](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMSYS2-blue) ![SSH](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSSH-blue)\n![许可证](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-green)\n\n![Claude Code](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude_Code-hook-ffab01) ![Amp](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FAmp-adapter-ffab01) ![Gemini CLI](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGemini_CLI-adapter-ffab01) ![GitHub Copilot](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitHub_Copilot-adapter-ffab01) ![Codex](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCodex-adapter-ffab01) ![Cursor](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCursor-adapter-ffab01) ![OpenCode](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FOpenCode-adapter-ffab01) ![Kilo CLI](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FKilo_CLI-adapter-ffab01) ![Kiro](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FKiro-adapter-ffab01) ![Kimi Code](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FKimi_Code-adapter-ffab01) ![Windsurf](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FWindsurf-adapter-ffab01) ![Antigravity](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FAntigravity-adapter-ffab01) ![OpenClaw](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FOpenClaw-adapter-ffab01) ![Rovo Dev CLI](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FRovo_Dev_CLI-adapter-ffab01) ![DeepAgents](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDeepAgents-adapter-ffab01)\n\n**当你的 AI 编码助手需要关注时，会播放游戏角色语音台词并显示视觉叠加通知——或者让助手通过 MCP 自行选择声音。**\n\nAI 编码助手在完成任务或需要权限时不会提醒你。你一不小心切换了标签页、注意力分散，结果又浪费了 15 分钟才重新进入工作状态。peon-ping 通过来自《魔兽争霸》、《星际争霸》、《传送门》、《塞尔达传说》等游戏的语音台词和醒目的屏幕弹窗来解决这个问题——它适用于 **Claude Code**、**Amp**、**GitHub Copilot**、**Codex**、**Cursor**、**OpenCode**、**Kilo CLI**、**Kiro**、**Kimi Code**、**Windsurf**、**Google Antigravity**、**Rovo Dev CLI**、**DeepAgents** 以及任何支持 MCP 的客户端。\n\n**观看实际效果** → [peonping.com](https:\u002F\u002Fpeonping.com\u002F)\n\n\u003Cvideo src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F149b6d15-65c2-41f2-9b56-13575ff8364b\" autoplay loop muted playsinline width=\"400\">\u003C\u002Fvideo>\n\n\u003C\u002Fdiv>\n\n---\n\n- [安装](#install)\n- [你会听到什么](#what-youll-hear)\n- [快速控制](#quick-controls)\n- [配置](#configuration)\n- [Peon 训练师](#peon-trainer)\n- [MCP 服务器](#mcp-server)\n- [多 IDE 支持](#multi-ide-support)\n- [远程开发](#remote-development-ssh--devcontainers--codespaces)\n- [移动通知](#mobile-notifications)\n- [音效包](#sound-packs)\n- [调试](#debugging)\n- [卸载](#uninstall)\n- [要求](#requirements)\n- [工作原理](#how-it-works)\n- [链接](#links)\n\n---\n\n## 安装\n\n### 方法 1：Homebrew（推荐）\n\n```bash\nbrew install PeonPing\u002Ftap\u002Fpeon-ping\n```\n\n然后运行 `peon-ping-setup` 注册钩子并下载音效包。适用于 macOS 和 Linux。\n\n### 方法 2：安装脚本（macOS、Linux、WSL2）\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.sh | bash\n```\n\n⚠️ 在 WSL2 中，必须安装 **ffmpeg** 才能使用非 **WAV** 格式的音效包。在 Debian 发行版中，请使用以下命令安装：\n\n```sh\nsudo apt update; sudo apt install -y ffmpeg\n```\n\n### 方法 3：Windows 安装程序\n\n```powershell\nInvoke-WebRequest -Uri \"https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.ps1\" -UseBasicParsing | Invoke-Expression\n```\n\n默认安装 5 个精选包（《魔兽争霸》、《星际争霸》、《传送门》）。再次运行可更新，同时保留配置和状态。或者 **[在 peonping.com 上交互式选择音效包](https:\u002F\u002Fpeonping.com\u002F#picker)**，获取自定义安装命令。\n\n有用的安装标志：\n\n- `--all` — 安装所有可用的音效包\n- `--packs=peon,sc_kerrigan,...` — 只安装特定的音效包\n- `--local` — 将音效包、配置和钩子安装到当前项目的 `.\u002F.claude\u002F` 目录下\n- `--global` — 显式全局安装（与默认设置相同）\n- `--init-local-config` — 仅创建 `.\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fconfig.json`\n\n`--local` 不会修改你的 shell 配置文件（不会注入全局 `peon` 别名或补全功能）。钩子会以绝对路径注册在项目级别的 `.\u002F.claude\u002Fsettings.json` 中，因此无论你在项目中的哪个工作目录，它们都能正常工作。\n\n示例：\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.sh | bash -s -- --all\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.sh | bash -s -- --packs=peon,sc_kerrigan\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.sh | bash -s -- --local\n```\n\n如果已经存在全局安装而你尝试进行本地安装（或反之），安装程序会提示你先移除现有的安装，以免发生冲突。\n\n### 方法 4：先克隆并检查\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping.git\ncd peon-ping\n.\u002Finstall.sh\n```\n\n### 方法 5：Nix（macOS、Linux）\n\n无需安装即可直接从源代码运行：\n\n```bash\nnix run github:PeonPing\u002Fpeon-ping -- status\nnix run github:PeonPing\u002Fpeon-ping -- packs install peon\n```\n\n或者将其安装到你的用户配置文件中：\n\n```bash\nnix profile install github:PeonPing\u002Fpeon-ping\n```\n\n开发环境（bats、shellcheck、nodejs）：\n\n```bash\nnix develop  # 或使用 direnv\n```\n\n#### Home Manager 模块（声明式配置）\n\n对于可重复的配置，可以使用 Home Manager 模块：\n\n```nix\n\n# 在你的 home.nix 或 flake.nix 中\n{ inputs, pkgs, ... }:\n\nlet\n  peonCursorAdapterPath = \"${inputs.peon-ping.packages.${pkgs.system}.default}\u002Fshare\u002Fpeon-ping\u002Fadapters\u002Fcursor.sh\";\nin {\n  imports = [ inputs.peon-ping.homeManagerModules.default ];\n\n  programs.peon-ping = {\n    enable = true;\n    package = inputs.peon-ping.packages.${pkgs.system}.default;\n\n    settings = {\n      default_pack = \"glados\";\n      volume = 0.7;\n      enabled = true;\n      desktop_notifications = true;\n      categories = {\n        \"session.start\" = true;\n        \"task.complete\" = true;\n        \"task.error\" = true;\n        \"input.required\" = true;\n        \"resource.limit\" = true;\n        \"user.spam\" = true;\n      };\n    };\n\n    # 从 og-packs（简单字符串表示法）和自定义源（包含 name + src 的 attrset）安装音效包\n    installPacks = [\n      \"peon\"\n      \"glados\"\n      \"sc_kerrigan\"\n      # 来自 GitHub 的自定义音效包（openpeon.com 注册表）\n      {\n        name = \"mr_meeseeks\";\n        src = pkgs.fetchFromGitHub {\n          owner = \"kasperhendriks\";\n          repo = \"openpeon-mrmeeseeks\";\n          rev = \"main\";  # 或使用提交哈希以确保可重复性\n          sha256 = \"sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=\";\n        };\n      }\n    ];\n    enableZshIntegration = true;\n  };\n\n  # 光标钩子\n  home.file.\".cursor\u002Fhooks.json\".text = builtins.toJSON {\n    version = 1;\n    hooks = {\n      afterAgentResponse = [{ command = \"bash ${peonCursorAdapterPath} afterAgentResponse\"; }];\n      stop               = [{ command = \"bash ${peonCursorAdapterPath} stop\"; }];\n    };\n  };\n}\n```\n\n**音效包安装**：`installPacks` 选项支持两种格式：\n- **简单字符串**（例如 `\"peon\"`、`\"glados\"`）——从 [og-packs](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fog-packs) 仓库获取\n- **自定义源**——一个包含 `name` 和 `src` 字段的 attrset，其中 `src` 可以是任何 Nix 获取器的结果（例如 `pkgs.fetchFromGitHub`）\n\n对于在 [openpeon.com](https:\u002F\u002Fopenpeon.com\u002F) 上列出的音效包，请找到其 GitHub 仓库链接，并使用 `pkgs.fetchFromGitHub`：\n```nix\n{\n  name = \"pack_name\";\n  src = pkgs.fetchFromGitHub {\n    owner = \"github-owner\";\n    repo = \"repo-name\";\n    rev = \"main\";  # 或者使用具体的提交哈希或标签\n    sha256 = \"\";   # 初次留空，Nix 会提示正确的哈希值\n  };\n}\n```\n\n**IDE 钩子**：peon-ping Home Manager 模块不会自动设置你的 IDE 钩子，以避免更新冲突。你需要根据自己的 IDE 配置方式自行定义这些钩子（见上文示例）。\n- peon-ping 提供了适用于多种 IDE 的适配脚本，例如 `cursor.sh` — 参见 [`adapters\u002F`](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Ftree\u002Fmain\u002Fadapters)\n- 你需要在钩子中调用这些脚本，例如：\n  ```sh\n  ${inputs.peon-ping.packages.${pkgs.system}.default}\u002Fshare\u002Fpeon-ping\u002Fadapters\u002F$YOUR_IDE.sh EVENT_NAME\n  ```\n  如上文光标示例所示。\n\n## 你会听到的内容\n\n| 事件 | CESP 分类 | 示例 |\n|---|---|---|\n| 会话开始 | `session.start` | *\"准备好了吗？\"*, *\"嗯？\"*, *\"你想做什么？\"* |\n| 任务完成 | `task.complete` | *\"加油！\"*, *\"我可以搞定。\"*, *\"好的，没问题。\"* |\n| 需要权限 | `input.required` | *\"有什么需要做的吗？\"*, *\"嗯？\"*, *\"你想干什么？\"* |\n| 工具或命令错误 | `task.error` | *\"我做不到。\"*, *\"该死！\"* |\n| 代理确认任务 | `task.acknowledge` | *\"明白。\"*, *\"马上处理。\"* *(默认关闭)* |\n| 使用率或令牌限制被触发 | `resource.limit` | *\"嘟嘟嘟。\"* *(取决于具体音效包)* |\n| 连续快速提示（10 秒内 3 次以上） | `user.spam` | *\"我很忙，别打扰我！\"* |\n\n此外，在每个屏幕（macOS\u002FWSL\u002FMSYS2）上还会显示大型覆盖式横幅通知，并在终端标签页标题中显示 `● 项目：已完成`——即使你在其他应用中，也能立即知道发生了什么。\n\npeon-ping 实现了 [Coding Event Sound Pack Specification (CESP)](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon)——一种开放标准，用于编码事件音效，任何智能型 IDE 都可以采用。\n\n## 快速控制\n\n在会议或配对会话期间需要静音声音和通知吗？有两种方法：\n\n| 方法 | 命令 | 适用场景 |\n|---|---|---|\n| **斜杠命令** | `\u002Fpeon-ping-toggle` | 在 Claude Code 中工作时 |\n| **CLI** | `peon toggle` | 从任何终端标签页 |\n\n其他 CLI 命令：\n\n```bash\npeon pause                # 静音\npeon resume               # 取消静音\npeon mute                 # “pause”的别名\npeon unmute               # “resume”的别名\npeon status               # 检查是否已暂停或启用（简洁）\npeon status --verbose     # 显示完整详情（通知、耳机、IDE 等）\npeon volume               # 显示当前音量\npeon volume 0.7           # 设置音量（0.0–1.0）\npeon rotation             # 显示当前轮换模式\npeon rotation random      # 设置轮换模式（随机|轮循|会话覆盖）\npeon packs list           # 列出已安装的声音包\npeon packs list --registry # 浏览注册表中所有可用包\npeon packs community      # 列出按信任等级分组的所有注册表包（Windows）\npeon packs search \u003Cquery> # 按名称搜索注册表包（Windows）\npeon packs install \u003Cp1,p2> # 从注册表安装包\npeon packs install --all  # 安装注册表中的所有包\npeon packs install-local \u003Cpath> # 从本地目录安装包\npeon packs use \u003Cname>     # 切换到特定包（在 Windows 上会自动从注册表安装）\npeon packs use --install \u003Cname>  # 切换到指定包，必要时从注册表安装\npeon packs next           # 循环切换到下一个包\npeon packs remove \u003Cp1,p2> # 移除特定包\npeon packs bind \u003Cname>    # 将包绑定到当前目录\npeon packs bind --pattern \u003Cpath> # 将包绑定到目录模式，例如 \"*\u002Fservices\"\npeon packs unbind         # 移除当前目录的绑定\npeon packs bindings       # 列出所有已分配的绑定\npeon notifications on     # 启用桌面通知\npeon notifications off    # 禁用桌面通知\npeon notifications overlay   # 使用大型叠加横幅（默认）\npeon notifications standard  # 使用标准系统通知\npeon notifications test      # 发送测试通知\npeon notifications position [pos]    # 获取\u002F设置通知位置（左上、中上、右上、左下、中下、右下）\npeon notifications dismiss [N]       # 获取\u002F设置自动关闭时间（秒）（0 = 持续显示）\npeon notifications label [text|reset] # 获取\u002F设置通知的项目标签覆盖\npeon notifications template [key] [fmt]  # 获取\u002F设置\u002F重置消息模板（键：停止、权限、错误、空闲、提问）\npeon preview              # 播放 session.start 中的所有声音\npeon preview \u003Ccategory>   # 播放特定类别中的所有声音\npeon preview --list       # 列出活动包中的所有类别\npeon mobile ntfy \u003Ctopic>  # 设置手机通知（免费）\npeon mobile off           # 禁用手机通知\npeon mobile test          # 发送测试通知\npeon debug on             # 启用调试日志\npeon debug off            # 禁用调试日志\npeon debug status         # 显示调试状态、日志目录、文件数量及总大小\npeon logs                 # 显示今日日志的最后 50 行\npeon logs --last N        # 显示所有日志文件中的最后 N 行\npeon logs --session ID    # 按会话 ID 过滤今日日志\npeon logs --session ID --all  # 在所有日志文件中搜索会话 ID\npeon logs --clear         # 删除所有日志文件（需确认）\npeon relay --daemon       # 启动音频中继（用于 SSH\u002Fdevcontainer）\npeon relay --stop         # 停止后台中继\n```\n\n`peon preview` 可用的 CESP 类别：`session.start`、`task.acknowledge`、`task.complete`、`task.error`、`input.required`、`resource.limit`、`user.spam`。 （扩展类别 `session.end` 和 `task.progress` 已在 CESP 规范中定义，并由包清单支持，但目前尚未由内置钩子事件触发。）\n\n支持选项卡补全——输入 `peon packs use \u003CTAB>` 即可查看可用包名。\n\n暂停会立即静音声音和桌面通知。暂停状态会持续到您恢复为止。暂停时标签页标题仍保持活跃。\n\n## 配置\n\npeon-ping 会在 Claude Code 中安装以下斜杠命令：\n\n- `\u002Fpeon-ping-toggle` — 静音\u002F取消静音声音\n- `\u002Fpeon-ping-config` — 更改任何设置（音量、包、类别等）\n- `\u002Fpeon-ping-rename \u003Cname>` — 为当前会话命名，该名称将显示在通知标题和终端标签页标题中（零令牌，被钩子拦截）；不提供参数则恢复为自动检测\n\n您也可以直接让 Claude 为您更改设置——例如“启用轮循包轮换”、“将音量设为 0.3”或“将 glados 添加到我的包轮换中”。无需手动编辑配置文件。\n\n配置文件的位置取决于安装方式：\n\n- 全局安装：`$CLAUDE_CONFIG_DIR\u002Fhooks\u002Fpeon-ping\u002Fconfig.json`（默认 `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fconfig.json`）\n- 本地安装：`.\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fconfig.json`\n\n```json\n{\n  \"volume\": 0.5,\n  \"categories\": {\n    \"session.start\": true,\n    \"task.acknowledge\": true,\n    \"task.complete\": true,\n    \"task.error\": true,\n    \"input.required\": true,\n    \"resource.limit\": true,\n    \"user.spam\": true\n  }\n}\n```\n\n### 独立控制\n\npeon-ping 提供三种可自由组合的独立控制：\n\n| 配置键 | 控制项 | 影响声音 | 影响桌面弹窗 | 影响手机推送 |\n|------------|----------|----------------|------------------------|---------------------|\n| `enabled` | 主音频开关 | ✅ 是 | ❌ 否 | ❌ 否 |\n| `desktop_notifications` | 桌面弹窗横幅 | ❌ 否 | ✅ 是 | ❌ 否 |\n| `mobile_notify.enabled` | 手机推送通知 | ❌ 否 | ❌ 否 | ✅ 是 |\n\n这意味着您可以：\n- 保留声音但禁用桌面弹窗：`peon notifications off`\n- 保留桌面弹窗但禁用声音：`peon pause`\n- 启用手机推送而不启用桌面弹窗：将 `desktop_notifications: false` 和 `mobile_notify.enabled: true`\n\n- **volume**: 0.0–1.0（安静到适合办公室）\n- **desktop_notifications**: `true`\u002F`false` — 独立于声音开关桌面通知弹窗（默认：`true`）。禁用后，声音仍会播放，但视觉弹窗会被屏蔽。移动通知不受影响。\n- **notification_style**: `\"overlay\"` 或 `\"standard\"` — 控制桌面通知的显示方式（默认：`\"overlay\"`）\n  - **overlay**: 大型、醒目的横幅——macOS 上为 JXA Cocoa 叠加层，WSL\u002FMSYS2 上为 Windows Forms 弹窗。点击叠加层会将终端窗口置顶（支持 Ghostty、Warp、iTerm2、Zed、Terminal.app）。在 iTerm2 中，点击不仅会将应用置顶，还会聚焦正确的标签页\u002F窗格\u002F窗口。\n  - **standard**: 系统通知——macOS 上使用 [`terminal-notifier`](https:\u002F\u002Fgithub.com\u002FjulienXX\u002Fterminal-notifier) \u002F `osascript`，WSL\u002FMSYS2 上使用 Windows 通知气泡。安装 `terminal-notifier` 后（`brew install terminal-notifier`），点击标准通知会自动将终端窗口置顶（支持 Ghostty、Warp、iTerm2、Zed、Terminal.app）。在原生 Windows 系统中，点击通知气泡会将 IDE 或终端窗口置顶（支持 VS Code、Cursor、Windsurf、Windows Terminal、PowerShell）。当有多个窗口打开时，通知会通过基于 PID 的进程树匹配，精准定位到触发事件的窗口。\n- **overlay_theme**: `\"jarvis\"`、`\"glass\"`、`\"sakura\"`，或省略以使用默认叠加层主题——仅适用于 macOS（默认：无）\n  - **jarvis**: 圆形 HUD，带有旋转弧线、刻度标记和进度环。\n  - **glass**: 玻璃质感面板，配有强调色条、进度线和时间戳。\n  - **sakura**: 极简禅意花园，点缀盆景树与飘落的樱花花瓣动画。\n- **categories**: 开关各个 CESP 声音分类（例如，`\"session.start\": false` 可禁用问候音）。\n- **annoyed_threshold \u002F annoyed_window_seconds**: 在 N 秒内收到多少条提示会触发 `user.spam` 彩蛋。\n- **silent_window_seconds**: 对持续时间少于 N 秒的任务，抑制 `task.complete` 音效及通知。（例如，设置为 `10` 表示只有超过 10 秒的任务才会发出音效。）\n- **session_start_cooldown_seconds**（数字，默认：`30`）：用于去重同时启动的多个工作区的问候音效（如同时打开 OpenCode 或 Cursor 并加载多个文件夹）。仅第一个会话的开始会播放问候音，此窗口内的后续会话则保持静音。设为 `0` 可禁用去重功能，始终播放问候音。\n- **suppress_subagent_complete**（布尔值，默认：`false`）：当子代理会话结束时，抑制 `task.complete` 音效及通知。当 Claude Code 的任务工具并行调度多个子代理时，每个子代理都会触发完成音效——将其设置为 `true`，则只会听到父会话的完成音效。\n- **default_pack**: 当没有更具体的规则适用时使用的回退包（默认：`\"peon\"`）。取代了旧的 `active_pack` 键——现有配置会在 `peon update` 时自动迁移。\n- **path_rules**: `{ \"pattern\": \"...\", \"pack\": \"...\" }` 对象数组。根据工作目录，使用 glob 匹配规则（`*`、`?`）为会话分配特定包。优先匹配第一个规则。该规则优先于 `pack_rotation` 和 `default_pack`；但会被 `session_override` 分配覆盖。\n  ```json\n  \"path_rules\": [\n    { \"pattern\": \"*\u002Fwork\u002Fclient-a\u002F*\", \"pack\": \"glados\" },\n    { \"pattern\": \"*\u002Fpersonal\u002F*\",      \"pack\": \"peon\" }\n  ]\n  ```\n- **pack_rotation**: 包名数组（如 `[\"peon\", \"sc_kerrigan\", \"peasant\"]`）。当 `pack_rotation_mode` 为 `random` 或 `round-robin` 时使用。留空 `[]` 则仅使用 `default_pack`（或 `path_rules`）。\n- **pack_rotation_mode**: `\"random\"`（默认）、`\"round-robin\"` 或 `\"session_override\"`。在 `random`\u002F`round-robin` 模式下，每个会话会从 `pack_rotation` 中随机选择一个包。而在 `session_override` 模式下，可通过 `\u002Fpeon-ping-use \u003Cpack>` 命令为每个会话指定包。无效或缺失的包会按层级顺序回退。（`\"agentskill\"` 被视为 `\"session_override\"` 的旧别名，仍可接受。）\n- **session_ttl_days**（数字，默认：7）：使超过 N 天的会话级包分配失效。防止在使用 `session_override` 模式时 `.state.json` 文件无限增长。\n- **headphones_only**（布尔值，默认：`false`）：仅在检测到耳机或外部音频设备时播放声音。启用后，若当前输出为内置扬声器，则会抑制声音——这在开放式办公室中非常实用。可通过 `peon status` 查看状态。支持 macOS（通过 `system_profiler`）和 Linux（通过 PipeWire `wpctl` 或 PulseAudio `pactl`）。\n- **suppress_sound_when_tab_focused**（布尔值，默认：`false`）：当触发钩子事件的终端标签页为当前活动\u002F聚焦的标签页时，跳过声音播放。后台标签页的声音仍会正常播放，作为提醒其他地方发生了某些事情。桌面和移动通知不受影响。适用于仅希望从未查看的标签页获取音频提示的情况。仅限 macOS（使用 `osascript` 检查前台应用及 iTerm2 标签页焦点）。\n- **meeting_detect** 检测麦克风是否正在使用，并暂时抑制音频，直到麦克风不再使用为止。通知仍会显示。\n- **notification_position**（字符串，默认：`\"top-center\"`）：叠加式通知在屏幕上的显示位置。选项包括：`\"top-left\"`、`\"top-center\"`、`\"top-right\"`、`\"bottom-left\"`、`\"bottom-center\"`、`\"bottom-right\"`。\n- **notification_dismiss_seconds**（数字，默认：4）：叠加式通知在 N 秒后自动消失。设置为 `0` 可使通知持续显示，需手动关闭。\n- **notification_all_screens**（布尔值，默认：`true`）：叠加式通知显示在所有屏幕上（`true`）或仅主屏幕上（`false`）。此前，主题叠加层（`glass`、`jarvis`、`sakura`）仅显示在单个屏幕上——使用这些主题的现有配置会自动迁移到 `false`。仅适用于 macOS。\n- **`CLAUDE_SESSION_NAME` 环境变量**：在启动 `claude` 之前设置，为会话命名自定义名称。该名称会同时显示在桌面通知标题和终端标签页标题中。优先级高于所有基于配置的命名方式。示例：`CLAUDE_SESSION_NAME=\"Auth Refactor\" claude` 或先执行 `export CLAUDE_SESSION_NAME=\"Feature: Auth\"` 再运行 `claude`。由于 peon-ping 作为该 Claude 实例的子进程运行，每个终端会自动获得各自的标题。\n- **notification_title_override**（字符串，默认：`\"\"`）：覆盖通知标题中显示的项目名称。为空时，项目名称将自动从 `\u002Fpeon-ping-rename` > `CLAUDE_SESSION_NAME` > `.peon-label` > `notification_title_script` > `project_name_map` > Git 仓库名 > 文件夹名中推断得出。\n- **notification_title_script**（字符串，默认：`\"\"`）：在事件发生时运行的 Shell 命令，用于动态计算项目名称。接收以下环境变量：`PEON_SESSION_ID`、`PEON_CWD`、`PEON_HOOK_EVENT`、`PEON_SESSION_NAME`。使用标准输出（截取前 50 个字符）；非零退出码则会传递到下一层次。示例：`\"basename $PEON_CWD\"`。\n- **project_name_map**（对象，默认：`{}`）：将目录路径映射为通知中显示的自定义项目标签。键为路径模式，值为显示名称。示例：`{ \"\u002Fhome\u002Fuser\u002Fwork\u002Fclient-a\": \"Client A\" }`。\n- **notification_templates**（对象，默认：`{}`）：针对通知事件的自定义消息格式字符串。键为事件类型（`stop`、`permission`、`error`、`idle`、`question`），值为带变量替换的模板字符串。可用变量包括：`{project}`、`{summary}`、`{tool_name}`、`{status}`、`{event}`。示例：`{ \"stop\": \"{project}: {summary}\", \"permission\": \"{project}: {tool_name} 需要批准\" }`。\n\n### 声音包选择层级\n\npeon-ping 通过一个五层的优先级体系来决定使用哪个声音包。最先找到有效且已安装的声音包即为最终选择：\n\n| 优先级 | 层级         | 来源               | 设置方法                     |\n|--------|--------------|--------------------|------------------------------|\n| 1（最高） | **session_override** | 每会话覆盖设置     | `\u002Fpeon-ping-use \u003Cpack>` 技能或 MCP |\n| 2      | **path_rules**   | 工作目录的 glob 匹配 | `peon packs bind` 或配置中的 `path_rules` |\n| 3      | **pack_rotation** | 随机或轮询列表     | 配置中的 `pack_rotation` 数组 + `pack_rotation_mode` |\n| 4      | **default_pack** | 静态回退           | `peon packs use \u003Cname>` 或配置中的 `default_pack` |\n| 5（最低） | **hardcoded**    | 内置默认           | `\"peon\"`                     |\n\n如果某一层引用了未安装的声音包，则会自动降级到下一层。\n\n### 按项目分配声音包（path_rules）\n\n根据目录路径为不同项目分配不同的声音包。可通过 CLI 或直接编辑 `config.json` 进行设置。\n\n**CLI（推荐）：**\n\n```bash\npeon packs bind glados                     # 将 glados 绑定到当前目录\npeon packs bind sc_kerrigan --pattern \"*\u002Fservices\u002F*\"  # 绑定到 glob 模式\npeon packs bind duke_nukem --install       # 绑定并从注册表安装所需包\npeon packs unbind                          # 移除当前目录的绑定\npeon packs unbind --pattern \"*\u002Fservices\u002F*\" # 移除特定模式的绑定\npeon packs bindings                        # 列出所有绑定\n```\n\n**手动配置：**\n\n```json\n\"path_rules\": [\n  { \"pattern\": \"*\u002Fwork\u002Fclient-a\u002F*\", \"pack\": \"glados\" },\n  { \"pattern\": \"*\u002Fpersonal\u002F*\",      \"pack\": \"peon\" },\n  { \"pattern\": \"*\u002Fservices\u002F*\",      \"pack\": \"sc_kerrigan\" }\n]\n```\n\n规则使用 glob 匹配（`*`, `?`）。优先匹配第一个规则。路径规则会覆盖 `pack_rotation` 和 `default_pack`，但会被 `session_override` 覆盖。\n\n## 常见用例\n\n### 只响声不弹窗\n\n想要语音反馈但不想有视觉干扰？\n\n```bash\npeon notifications off\n```\n\n这将保持所有声音类别正常播放，同时屏蔽桌面通知横幅。若已配置移动通知，则仍会正常工作。\n\n你也可以使用别名：\n\n```bash\npeon popups off\n```\n\n### 仅通知无声模式\n\n想要视觉提醒但不要声音？\n\n```bash\npeon pause  # 或在配置中将 \"enabled\" 设置为 false\n```\n\n当 `desktop_notifications: true` 时，你会收到弹窗提示，但不会有声音。\n\n### 完全静音\n\n禁用所有功能：\n\n```bash\npeon pause\npeon notifications off\npeon mobile off\n```\n\n## Peon 训练师\n\n你的 peon 也是你的私人教练。内置 Pavel 风格的每日锻炼模式——那个曾经喊着“干活干活”的兽人现在会催促你做俯卧撑和深蹲。\n\n### 快速开始\n\n```bash\npeon trainer on              # 启动训练模式\npeon trainer goal 200        # 设置每日目标（默认：300\u002F300）\n# ... 编码一段时间后，peon 大约每 20 分钟提醒一次 ...\npeon trainer log 25 pushups  # 记录完成情况\npeon trainer log 30 squats\npeon trainer status          # 查看进度\n```\n\n### 工作原理\n\n训练提醒与你的编码会话同步进行。当你开始新会话时，peon 会立即鼓励你先做俯卧撑再写代码。随后，每活跃编码约 20 分钟，你就会听到 peon 催促你继续锻炼。无需后台守护进程。使用 `peon trainer log` 记录完成次数，进度将在午夜自动重置。\n\n### 命令\n\n| 命令            | 描述                           |\n|-----------------|--------------------------------|\n| `peon trainer on` | 启动训练模式                   |\n| `peon trainer off` | 关闭训练模式                   |\n| `peon trainer status` | 查看今日进度                 |\n| `peon trainer log \u003Cn> \u003Cexercise>` | 记录锻炼次数（例如 `log 25 pushups`） |\n| `peon trainer goal \u003Cn>` | 设置所有锻炼项目的总目标   |\n| `peon trainer goal \u003Cexercise> \u003Cn>` | 设置单个锻炼项目的目标     |\n\n### Claude Code 技能\n\n在 Claude Code 中，你可以在不退出对话的情况下记录锻炼次数：\n\n```\n\u002Fpeon-ping-log 25 pushups\n\u002Fpeon-ping-log 30 squats\n```\n\n### 自定义语音提示\n\n将你的音频文件放入 `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Ftrainer\u002Fsounds\u002F` 目录：\n\n```\ntrainer\u002Fsounds\u002Fsession_start\u002F  # 会话开场（“先做俯卧撑，再写代码！Zug zug!”）\ntrainer\u002Fsounds\u002Fremind\u002F         # 提醒语句（“有什么需要做的吗？是的。俯卧撑！”）\ntrainer\u002Fsounds\u002Flog\u002F            # 确认语句（“干活干活！肌肉可能正在变大！”）\ntrainer\u002Fsounds\u002Fcomplete\u002F       # 庆祝语句（“Zug zug！人类完成了所有动作！”）\ntrainer\u002Fsounds\u002Fslacking\u002F       # 失望语句（“Peon 非常失望。”）\n```\n\n更新 `trainer\u002Fmanifest.json` 以注册你的音频文件。\n\n## MCP 服务器\n\npeon-ping 内置了一个 [MCP（模型上下文协议）](https:\u002F\u002Fmodelcontextprotocol.io\u002F) 服务器，因此任何兼容 MCP 的 AI 助手都可以通过工具调用直接播放声音，无需额外钩子。\n\n关键区别在于：**由助手自行选择声音**。助手不会在每个事件上自动播放固定声音，而是调用 `play_sound` 并明确指定所需的声音——例如构建失败时播放 `duke_nukem\u002FSonOfABitch`，读取文件时播放 `sc_kerrigan\u002FIReadYou`。\n\n### 设置\n\n在你的 MCP 客户端配置中添加以下内容（Claude Desktop、Cursor 等）：\n\n```json\n{\n  \"mcpServers\": {\n    \"peon-ping\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fpath\u002Fto\u002Fpeon-ping\u002Fmcp\u002Fpeon-mcp.js\"]\n    }\n  }\n}\n```\n\n若通过 Homebrew 安装：`$(brew --prefix peon-ping)\u002Flibexec\u002Fmcp\u002Fpeon-mcp.js`。完整设置说明请参阅 [`mcp\u002FREADME.md`](mcp\u002FREADME.md)。\n\n### 助手可执行的功能\n\n| 功能             | 描述                                   |\n|------------------|----------------------------------------|\n| **`play_sound`** | 按键播放一个或多个声音（如 `duke_nukem\u002FSonOfABitch`、`peon\u002FPeonReady1`） |\n| **`peon-ping:\u002F\u002Fcatalog`** | 完整的声音包目录作为 MCP 资源——客户端只需预取一次，无需重复调用工具 |\n| **`peon-ping:\u002F\u002Fpack\u002F{name}`** | 单个声音包的详细信息及可用声音键     |\n\n需 Node.js 18+。由 [@tag-assistant](https:\u002F\u002Fgithub.com\u002Ftag-assistant) 贡献。\n\n## 多IDE支持\n\npeon-ping 可与任何支持钩子的代理型IDE配合使用。适配器会将IDE特定的事件转换为[CESP标准](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon)。\n\n| IDE | 状态 | 设置 |\n|---|---|---|\n| **Claude Code** | 内置 | `curl \\| bash` 安装即可完成所有配置 |\n| **Amp** | 适配器 | `bash adapters\u002Famp.sh` \u002F `powershell adapters\u002Famp.ps1`（[设置](#amp-setup)） |\n| **Gemini CLI** | 适配器 | 添加指向 `adapters\u002Fgemini.sh`（或 Windows 上的 `.ps1`）的钩子（[设置](#gemini-cli-setup)） |\n| **GitHub Copilot** | 适配器 | 将钩子添加到 `.github\u002Fhooks\u002Fhooks.json`，指向 `adapters\u002Fcopilot.sh`（或 `.ps1`）（[设置](#github-copilot-setup)） |\n| **OpenAI Codex** | 适配器 | 先安装 peon-ping 运行时，再在 `~\u002F.codex\u002Fconfig.toml` 中添加 `notify` 配置，指向 `adapters\u002Fcodex.sh`（或 `.ps1`）（[设置](#openai-codex-setup)） |\n| **Cursor** | 内置 | `curl \\| bash`、`peon-ping-setup` 或 Windows 的 `install.ps1` 会自动检测并注册钩子。在 Windows 上，请启用 **设置 → 功能 → 第三方技能**，以便 Cursor 加载 `~\u002F.claude\u002Fsettings.json` 来播放会话开始\u002F结束的声音。 |\n| **OpenCode** | 适配器 | `bash adapters\u002Fopencode.sh` \u002F `powershell adapters\u002Fopencode.ps1`（[设置](#opencode-setup)） |\n| **Kilo CLI** | 适配器 | `bash adapters\u002Fkilo.sh` \u002F `powershell adapters\u002Fkilo.ps1`（[设置](#kilo-cli-setup)） |\n| **Kiro** | 适配器 | 添加指向 `adapters\u002Fkiro.sh`（或 `.ps1`）的钩子条目（[设置](#kiro-setup)） |\n| **Windsurf** | 适配器 | 添加指向 `adapters\u002Fwindsurf.sh`（或 `.ps1`）的钩子条目（[设置](#windsurf-setup)） |\n| **Google Antigravity** | 适配器 | `bash adapters\u002Fantigravity.sh` \u002F `powershell adapters\u002Fantigravity.ps1` |\n| **Kimi Code** | 适配器 | `bash adapters\u002Fkimi.sh --install` \u002F `powershell adapters\u002Fkimi.ps1 -Install`（[设置](#kimi-code-setup)） |\n| **OpenClaw** | 适配器 | 从你的 OpenClaw 技能中调用 `adapters\u002Fopenclaw.sh \u003Cevent>`（或 `openclaw.ps1`） |\n| **Rovo Dev CLI** | 适配器 | 如果存在 `~\u002F.rovodev`，则由 `install.sh` 自动注册；否则需手动将钩子添加到 `~\u002F.rovodev\u002Fconfig.yml`（[设置](#rovo-dev-cli-setup)） |\n| **DeepAgents** | 适配器 | `bash adapters\u002Fdeepagents.sh` \u002F `powershell adapters\u002Fdeepagents.ps1`（[设置](#deepagents-setup)） |\n\n> **Windows:** 所有适配器都提供原生 PowerShell 版本（`.ps1`）。Windows 安装程序（`install.ps1`）会将这些文件复制到 `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002F`。文件系统监视器（Amp、Antigravity、Kimi）使用 .NET 的 `FileSystemWatcher` 而不是 fswatch\u002Finotifywait——无需额外依赖。\n\n### OpenAI Codex 设置\n\nCodex 支持通过适配器实现，并不会由 `peon-ping-setup` 自动注册。\n\nCodex 适配器期望 peon-ping 运行时位于 `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002F`，即使你只使用 Codex 而不使用 Claude Code 也是如此。\n\n**设置：**\n\n1. 先安装 peon-ping 运行时：\n\n   ```bash\n   bash \"$(brew --prefix peon-ping)\"\u002Flibexec\u002Finstall.sh --no-rc\n   ```\n\n   或使用标准安装脚本：\n\n   ```bash\n   curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.sh | bash -s -- --no-rc\n   ```\n\n2. 在 `~\u002F.codex\u002Fconfig.toml` 中添加以下内容：\n\n   ```toml\n   notify = [\"bash\", \"~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fcodex.sh\"]\n   ```\n\n3. 重启 Codex。\n\n如果你通过 Homebrew 安装，运行时文件会管理在 `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002F` 目录下，而 Codex 适配器会将 Codex 的通知事件转发到该共享运行时环境中。\n\n### Amp 设置\n\n这是用于 [Amp](https:\u002F\u002Fampcode.com)（由 Sourcegraph 开发）的文件系统监视器适配器。Amp 不像 Claude Code 那样暴露事件钩子，因此此适配器会监视 Amp 在磁盘上的线程文件，并检测代理何时完成一轮交互。\n\n**设置：**\n\n1. 确保已安装 peon-ping（`curl -fsSL https:\u002F\u002Fpeonping.com\u002Finstall | bash`）\n\n2. 安装 `fswatch`（macOS）或 `inotify-tools`（Linux）：\n\n   ```bash\n   brew install fswatch        # macOS\n   sudo apt install inotify-tools  # Linux\n   ```\n\n3. 启动监视器：\n\n   ```bash\n   bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Famp.sh        # 前台运行\n   bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Famp.sh &       # 后台运行\n   ```\n\n**事件映射：**\n\n- 新线程文件创建 → 欢迎音效（*“准备好了吗？”*、*“是吗？”*）\n- 线程文件停止更新 + 代理完成一轮交互 → 完成音效（*“工作，工作。”*、*“任务完成了！”*）\n\n**工作原理：**\n\n适配器会监视 `~\u002F.local\u002Fshare\u002Famp\u002Fthreads\u002F` 目录下的 JSON 文件变化。当线程文件停止更新（空闲超时为 1 秒），且最后一则消息来自助手且包含文本内容（而非待处理的工具调用）时，它会发出 `Stop` 事件——表示代理已完成工作，正在等待你的输入。\n\n**环境变量：**\n\n| 变量 | 默认值 | 描述 |\n|---|---|---|\n| `AMP_DATA_DIR` | `~\u002F.local\u002Fshare\u002Famp` | Amp 数据目录 |\n| `AMP_THREADS_DIR` | `$AMP_DATA_DIR\u002Fthreads` | 要监视的线程目录 |\n| `AMP_IDLE_SECONDS` | `1` | 在发出 Stop 事件前的无变化秒数 |\n| `AMP_STOP_COOLDOWN` | `10` | 每个线程两次 Stop 事件之间的最小间隔秒数 |\n\n### GitHub Copilot 设置\n\n一个与 [GitHub Copilot](https:\u002F\u002Fgithub.com\u002Ffeatures\u002Fcopilot) 兼容的 Shell 适配器，完全符合 [CESP v1.0](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) 标准。\n\n**设置步骤：**\n\n1. 确保已安装 peon-ping (`curl -fsSL https:\u002F\u002Fpeonping.com\u002Finstall | bash`)\n\n2. 在你的仓库（默认分支）中创建 `.github\u002Fhooks\u002Fhooks.json` 文件：\n\n   ```json\n   {\n     \"version\": 1,\n     \"hooks\": {\n       \"sessionStart\": [\n         {\n           \"type\": \"command\",\n           \"bash\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fcopilot.sh sessionStart\"\n         }\n       ],\n       \"userPromptSubmitted\": [\n         {\n           \"type\": \"command\",\n           \"bash\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fcopilot.sh userPromptSubmitted\"\n         }\n       ],\n       \"postToolUse\": [\n         {\n           \"type\": \"command\",\n           \"bash\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fcopilot.sh postToolUse\"\n         }\n       ],\n       \"errorOccurred\": [\n         {\n           \"type\": \"command\",\n           \"bash\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fcopilot.sh errorOccurred\"\n         }\n       ]\n     }\n   }\n   ```\n\n3. 提交并合并到你的默认分支。这些钩子将在你下一次使用 Copilot 代理时生效。\n\n**事件映射：**\n\n- `sessionStart` → 欢迎音效（“准备好工作了吗？”、“是的吗？”）\n- `userPromptSubmitted` → 第一条提示为问候，后续则触发垃圾信息检测\n- `postToolUse` → 完成音效（“工作，工作。”、“任务完成了！”）\n- `errorOccurred` → 错误音效（“我做不到。”）\n- `preToolUse` → 跳过（噪音太大）\n- `sessionEnd` → 无音效（session.end 尚未实现）\n\n**功能特性：**\n\n- **声音播放**：通过 `afplay`（macOS）、`pw-play`\u002F`paplay`\u002F`ffplay`（Linux）实现——优先级顺序与 Shell 钩子相同。\n- **CESP 事件映射**：GitHub Copilot 钩子映射到标准 CESP 类别（`session.start`、`task.complete`、`task.error`、`user.spam`）。\n- **桌面通知**：默认显示大型覆盖式横幅通知，或常规通知。\n- **垃圾信息检测**：若在 10 秒内连续收到 3 条以上快速提示，则触发 `user.spam` 语音提示。\n- **会话跟踪**：为每个 Copilot 会话 ID 分别标记会话。\n\n### OpenCode 设置\n\n一个原生 TypeScript 插件，用于 [OpenCode](https:\u002F\u002Fopencode.ai\u002F)，完全符合 [CESP v1.0](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) 标准。\n\n**快速安装：**\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Fadapters\u002Fopencode.sh | bash\n```\n\n安装程序会将 `peon-ping.ts` 复制到 `~\u002F.config\u002Fopencode\u002Fplugins\u002F`，并在 `~\u002F.config\u002Fopencode\u002Fpeon-ping\u002Fconfig.json` 中创建配置文件。插件包存储在共享的 CESP 路径下（`~\u002F.openpeon\u002Fpacks\u002F`）。\n\n**功能特性：**\n\n- **声音播放**：通过 `afplay`（macOS）、`pw-play`\u002F`paplay`\u002F`ffplay`（Linux）实现——优先级顺序与 Shell 钩子相同。\n- **CESP 事件映射**：`session.created`、`session.idle`、`session.error`、`permission.asked` 以及快速提示检测等均映射到标准 CESP 类别。\n- **桌面通知**：默认显示大型覆盖式横幅通知（使用 JXA Cocoa，在所有屏幕上可见），或通过 [`terminal-notifier`](https:\u002F\u002Fgithub.com\u002FjulienXX\u002Fterminal-notifier) \u002F `osascript` 发送常规通知。仅当终端未处于焦点状态时才会触发。\n- **终端焦点检测**：在发送通知前，通过 AppleScript 检查你的终端应用（Terminal、iTerm2、Warp、Alacritty、kitty、WezTerm、ghostty、Hyper）是否位于前台。\n- **标签页标题**：更新终端标签页以显示任务状态（“● 项目：正在工作…”、“✓ 项目：完成”、“✗ 项目：出错”）。\n- **插件包切换**：从配置中读取 `default_pack`（对于旧版配置则回退到 `active_pack`），并在运行时加载该包的 `openpeon.json` 清单文件。`path_rules` 可根据工作目录覆盖默认包。\n- **防重复逻辑**：避免同一类别中的声音连续两次播放。\n- **垃圾信息检测**：若在 10 秒内连续收到 3 条以上快速提示，则触发 `user.spam` 语音提示。\n\n\u003Cdetails>\n\u003Csummary>🖼️ 截图：带有自定义 peon 图标的桌面通知\u003C\u002Fsummary>\n\n![peon-ping OpenCode 通知](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FPeonPing_peon-ping_readme_cecac425801f.png)\n\n\u003C\u002Fdetails>\n\n> **提示**：安装 `terminal-notifier`（`brew install terminal-notifier`），以获得支持副标题和分组的更丰富通知。\n\n\u003Cdetails>\n\u003Csummary>🎨 可选：为通知自定义 peon 图标\u003C\u002Fsummary>\n\n默认情况下，`terminal-notifier` 会显示通用的 Terminal 图标。随附脚本使用 macOS 自带工具（`sips` + `iconutil`）将其替换为 peon 图标——无需额外依赖。\n\n```bash\nbash \u003C(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Fadapters\u002Fopencode\u002Fsetup-icon.sh)\n```\n\n或者，如果你已在本地安装（Homebrew 或 git clone）：\n\n```bash\nbash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fopencode\u002Fsetup-icon.sh\n```\n\n该脚本会自动查找 peon 图标（Homebrew libexec、OpenCode 配置或 Claude hooks 目录），生成合适的 `.icns` 文件，备份原始 `Terminal.icns`，并进行替换。在 `brew upgrade terminal-notifier` 后请重新运行。\n\n> **未来**：待 [jamf\u002FNotifier](https:\u002F\u002Fgithub.com\u002Fjamf\u002FNotifier) 上架 Homebrew（[#32](https:\u002F\u002Fgithub.com\u002Fjamf\u002FNotifier\u002Fissues\u002F32)）后，插件将迁移到该工具——Notifier 内置 `--rebrand` 支持，无需任何图标修改技巧。\n\n\u003C\u002Fdetails>\n\n### Kilo CLI 设置\n\n一个原生 TypeScript 插件，用于 [Kilo CLI](https:\u002F\u002Fgithub.com\u002Fkilocode\u002Fcli)，完全符合 [CESP v1.0](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) 标准。Kilo CLI 是 OpenCode 的一个分支，使用相同的插件系统——此安装程序会下载 OpenCode 插件，并针对 Kilo 进行补丁处理。\n\n**快速安装：**\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Fadapters\u002Fkilo.sh | bash\n```\n\n安装程序会将 `peon-ping.ts` 复制到 `~\u002F.config\u002Fkilo\u002Fplugins\u002F`，并在 `~\u002F.config\u002Fkilo\u002Fpeon-ping\u002Fconfig.json` 中创建配置文件。插件包存储在共享的 CESP 路径下（`~\u002F.openpeon\u002Fpacks\u002F`）。\n\n**功能特性：** 与 [OpenCode 适配器](#opencode-setup) 相同——声音播放、CESP 事件映射、桌面通知、终端焦点检测、标签页标题、插件包切换、防重复逻辑以及垃圾信息检测。\n\n### Gemini CLI 设置\n\n适用于 **Gemini CLI** 的 Shell 适配器，完全符合 [CESP v1.0](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) 规范。\n\n**设置步骤：**\n\n1. 确保已安装 peon-ping（`curl -fsSL https:\u002F\u002Fpeonping.com\u002Finstall | bash`）。\n\n2. 将以下钩子添加到你的 `~\u002F.gemini\u002Fsettings.json` 文件中：\n\n   ```json\n    {\n      \"hooks\": {\n        \"SessionStart\": [\n          {\n            \"matcher\": \"startup\",\n            \"hooks\": [\n              {\n                \"name\": \"peon-start\",\n                \"type\": \"command\",\n                \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fgemini.sh SessionStart\"\n              }\n            ]\n          }\n        ],\n        \"AfterAgent\": [\n          {\n            \"matcher\": \"*\",\n            \"hooks\": [\n              {\n                \"name\": \"peon-after-agent\",\n                \"type\": \"command\",\n                \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fgemini.sh AfterAgent\"\n              }\n            ]\n          }\n        ],\n        \"AfterTool\": [\n          {\n            \"matcher\": \"*\",\n            \"hooks\": [\n              {\n                \"name\": \"peon-after-tool\",\n                \"type\": \"command\",\n                \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fgemini.sh AfterTool\"\n              }\n            ]\n          }\n        ],\n        \"Notification\": [\n          {\n            \"matcher\": \"*\",\n            \"hooks\": [\n              {\n                \"name\": \"peon-notification\",\n                \"type\": \"command\",\n                \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fgemini.sh Notification\"\n              }\n            ]\n          }\n        ]\n      }\n    }\n   ```\n\n**事件映射：**\n\n- `SessionStart`（启动）→ 欢迎音效（“准备好了吗？”、“是的吗？”）\n- `AfterAgent` → 任务完成音效（“工作，工作。”、“完成了！”）\n- `AfterTool` → 成功 = 任务完成音效，失败 = 错误音效（“我做不到。”）\n- `Notification` → 系统通知\n\n### Windsurf 设置\n\n将以下内容添加到 `~\u002F.codeium\u002Fwindsurf\u002Fhooks.json`（用户级别）或 `.windsurf\u002Fhooks.json`（工作区级别）：\n\n```json\n{\n  \"hooks\": {\n    \"post_cascade_response\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fwindsurf.sh post_cascade_response\", \"show_output\": false }\n    ],\n    \"pre_user_prompt\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fwindsurf.sh pre_user_prompt\", \"show_output\": false }\n    ],\n    \"post_write_code\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fwindsurf.sh post_write_code\", \"show_output\": false }\n    ],\n    \"post_run_command\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fwindsurf.sh post_run_command\", \"show_output\": false }\n    ]\n  }\n}\n```\n\n### Kiro 设置\n\n创建 `~\u002F.kiro\u002Fagents\u002Fpeon-ping.json` 文件：\n\n```json\n{\n  \"name\": \"peon-ping\",\n  \"hooks\": {\n    \"agentSpawn\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkiro.sh\" }\n    ],\n    \"userPromptSubmit\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkiro.sh\" }\n    ],\n    \"stop\": [\n      { \"command\": \"bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkiro.sh\" }\n    ]\n  }\n}\n```\n\n`preToolUse` 和 `postToolUse` 被有意排除——它们会在每次调用工具时触发，会产生大量噪音。\n\n### Rovo Dev CLI 设置\n\n适用于 Atlassian 的 [Rovo Dev CLI](https:\u002F\u002Fdeveloper.atlassian.com\u002Fcloud\u002Frovo\u002F) 的 Shell 适配器，完全符合 [CESP v1.0](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) 规范。\n\n**自动设置：**\n\n如果在运行 `install.sh` 或 `peon-ping-setup` 时存在 `~\u002F.rovodev\u002Fconfig.yml` 文件，则会自动注册事件钩子。\n\n**手动设置：**\n\n1. 确保已安装 peon-ping（`curl -fsSL https:\u002F\u002Fpeonping.com\u002Finstall | bash`）。\n\n2. 将以下内容添加到 `~\u002F.rovodev\u002Fconfig.yml` 文件中：\n\n   ```yaml\n   eventHooks:\n     events:\n       - name: on_complete\n         commands:\n           - command: bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Frovodev.sh on_complete\n       - name: on_error\n         commands:\n           - command: bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Frovodev.sh on_error\n       - name: on_tool_permission\n         commands:\n           - command: bash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Frovodev.sh on_tool_permission\n   ```\n\n3. 重启 Rovo Dev CLI 以使钩子生效。\n\n**事件映射：**\n\n- `on_complete` → 完成音效（“工作，工作。”、“完成了！”）\n- `on_error` → 错误音效（“我做不到。”、“该死！”）\n- `on_tool_permission` → 权限提示音效（“有什么需要做的吗？”、“嗯？”）\n\n**功能：**\n\n- **声音播放** 通过 `afplay`（macOS）、`pw-play`\u002F`paplay`\u002F`ffplay`（Linux）实现——与 Shell 钩子具有相同的优先级链。\n- **CESP 事件映射** — Rovo Dev 事件映射到标准 CESP 类别（`task.complete`、`task.error`、`input.required`）。\n- **桌面通知** — 默认为大型覆盖式横幅，或使用标准通知。\n- **防抖动** — 抑制快速连续完成时产生的重复音效。\n\n### Kimi Code 设置\n\n适用于 [Kimi Code CLI](https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-cli)（MoonshotAI）的文件系统监视器适配器。Kimi Code 会将 Wire Mode 事件写入 `~\u002F.kimi\u002Fsessions\u002F` 目录——此适配器作为后台守护进程监视这些文件，并将事件转换为 CESP 格式。\n\n```bash\n# 安装（启动后台守护进程）\nbash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkimi.sh --install\n\n# 查看状态 \u002F 停止\nbash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkimi.sh --status\nbash ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Fadapters\u002Fkimi.sh --uninstall\n```\n\n需要在 macOS 上安装 `fswatch`（`brew install fswatch`），或在 Linux 上安装 `inotifywait`（`apt install inotify-tools`）。`curl | bash` 安装程序会自动检测 Kimi Code 并启动守护进程。\n\n**事件映射：**\n\n- 新会话 → 欢迎音效（“准备好了吗？”、“是的吗？”）\n- 代理回合结束 → 完成音效（“工作，工作。”、“完成了！”）\n- 上下文压缩 → 令牌限制音效\n- 子代理生成 → 子代理跟踪音效\n\n## 远程开发（SSH \u002F Devcontainers \u002F Codespaces）\n\n在远程服务器或容器内进行编码？peon-ping 会自动检测 SSH 会话、Devcontainers 和 Codespaces，然后通过你本地机器上运行的轻量级中继路由音频和通知。\n\n### SSH 设置\n\n1. **在你的本地机器上**，启动中继：\n   ```bash\n   peon relay --daemon\n   ```\n\n2. **使用端口转发进行 SSH 连接**：\n   ```bash\n   ssh -R 19998:localhost:19998 your-server\n   ```\n\n3. **在远程主机上安装 peon-ping**——它会自动检测 SSH 会话，并通过转发的端口将音频请求发送回你本地的中继。\n\n就是这样。声音将在你的笔记本电脑上播放，而不是在远程服务器上。\n\n可选的 SSH 路由模式：\n\n```bash\npeon ssh-audio relay   # 默认，始终使用中继\npeon ssh-audio auto    # 尝试使用中继，若失败则回退到 SSH 主机本地播放\npeon ssh-audio local   # 始终在 SSH 主机上播放\n```\n\n### Devcontainers \u002F Codespaces\n\n无需端口转发——peon-ping 会自动检测 `REMOTE_CONTAINERS` 和 `CODESPACES` 环境变量，并将音频路由到 `host.docker.internal:19998`。只需在你的主机上运行 `peon relay --daemon` 即可。\n\n### 中继命令\n\n```bash\npeon relay                # 在前台启动中继\npeon relay --daemon       # 在后台启动\npeon relay --stop         # 停止后台中继\npeon relay --status       # 检查中继是否正在运行\npeon relay --port=12345   # 自定义端口（默认：19998）\npeon relay --bind=0.0.0.0 # 监听所有接口（安全性较低）\n```\n\n环境变量：`PEON_RELAY_PORT`、`PEON_RELAY_HOST`、`PEON_RELAY_BIND`。\n\n如果 peon-ping 检测到 SSH 或容器会话，但无法连接到中继，则会在 `SessionStart` 事件时打印设置说明。\n\n### 基于分类的 API（用于轻量级远程钩子）\n\n中继支持基于分类的端点，可在服务器端处理声音选择。这对于未安装 peon-ping 的远程机器非常有用——远程钩子只需发送一个分类名称，中继就会从当前激活的声音包中随机选择一个声音播放。\n\n**端点：**\n\n| 端点 | 描述 |\n|---|---|\n| `GET \u002Fhealth` | 健康检查（返回“OK”） |\n| `GET \u002Fplay?file=\u003Cpath>` | 播放特定声音文件（旧版） |\n| `GET \u002Fplay?category=\u003Ccat>` | 从分类中随机播放声音（推荐） |\n| `POST \u002Fnotify` | 发送桌面通知 |\n\n**远程钩子示例（`scripts\u002Fremote-hook.sh`）：**\n\n```bash\n#!\u002Fbin\u002Fbash\nRELAY_URL=\"${PEON_RELAY_URL:-http:\u002F\u002F127.0.0.1:19998}\"\nEVENT=$(cat | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get('hook_event_name',''))\" 2>\u002Fdev\u002Fnull)\ncase \"$EVENT\" in\n  SessionStart)      CATEGORY=\"session.start\" ;;\n  Stop)              CATEGORY=\"task.complete\" ;;\n  PermissionRequest) CATEGORY=\"input.required\" ;;\n  *)                 exit 0 ;;\nesac\ncurl -sf \"${RELAY_URL}\u002Fplay?category=${CATEGORY}\" >\u002Fdev\u002Fnull 2>&1 &\n```\n\n将此脚本复制到您的远程机器，并在 `~\u002F.claude\u002Fsettings.json` 中注册：\n\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [{\"command\": \"bash \u002Fpath\u002Fto\u002Fremote-hook.sh\"}],\n    \"Stop\": [{\"command\": \"bash \u002Fpath\u002Fto\u002Fremote-hook.sh\"}],\n    \"PermissionRequest\": [{\"command\": \"bash \u002Fpath\u002Fto\u002Fremote-hook.sh\"}]\n  }\n}\n```\n\n中继会读取您本地机器上的 `config.json` 文件以获取当前激活的声音包和音量，加载该声音包的清单，并在避免重复的情况下随机选择一个声音。\n\n## 移动通知\n\n当任务完成或需要关注时，您可以在手机上收到推送通知——这在您离开办公桌时非常有用。\n\n### 快速入门（ntfy.sh — 免费，无需账号）\n\n1. 在您的手机上安装 [ntfy 应用程序](https:\u002F\u002Fntfy.sh)\n2. 在应用中订阅一个唯一的主题（例如 `my-peon-notifications`）\n3. 运行：\n   ```bash\n   peon mobile ntfy my-peon-notifications\n   ```\n\n还支持 [Pushover](https:\u002F\u002Fpushover.net) 和 [Telegram](https:\u002F\u002Fcore.telegram.org\u002Fbots)：\n\n```bash\npeon mobile pushover \u003Cuser_key> \u003Capp_token>\npeon mobile telegram \u003Cbot_token> \u003Cchat_id>\n```\n\n### 移动命令\n\n```bash\npeon mobile on            # 启用移动通知\npeon mobile off           # 禁用移动通知\npeon mobile status        # 显示当前配置\npeon mobile test          # 发送测试通知\n```\n\n移动通知会在每次事件发生时触发，无论窗口是否处于焦点状态——它们与桌面通知和声音是独立的。\n\n## 声音包\n\n涵盖魔兽争霸、星际争霸、红色警戒、传送门、塞尔达传说、Dota 2、地狱特工2、上古卷轴等共 165 个声音包。默认安装包含 5 个精选声音包：\n\n| 包 | 角色 | 声音 |\n|---|---|---|\n| `peon`（默认） | 半兽人劳工（魔兽争霸 III） | “准备好了吗？”，“干活，干活！”，“好的，好的。” |\n| `peasant` | 人类农民（魔兽争霸 III） | “是的，大人？”，“活干完了！”，“准备好了，长官。” |\n| `sc_kerrigan` | 莎拉·凯莉根（星际争霸） | “我明白了”，“现在怎么办？”，“真好笑啊？” |\n| `sc_battlecruiser` | 战列巡洋舰（星际争霸） | “战列巡洋舰已就绪”，“动手吧”，“开火！” |\n| `glados` | GLaDOS（传送门） | “哦，原来是你啊”，“你这个怪物”，“你整个团队都死了。” |\n\n**[浏览所有带有音频预览的声音包 → openpeon.com\u002Fpacks](https:\u002F\u002Fopenpeon.com\u002Fpacks)**\n\n使用 `--all` 可以安装所有声音包，或者随时切换声音包：\n\n```bash\npeon packs use glados             # 切换到特定声音包\npeon packs use --install glados   # 一步完成安装并切换\npeon packs next                   # 循环切换到下一个声音包\npeon packs list                   # 列出所有已安装的声音包\npeon packs list --registry        # 浏览所有可用的声音包\npeon packs install glados,murloc  # 安装指定声音包\npeon packs install --all          # 安装注册表中的所有声音包\n```\n\n想添加自己的声音包吗？请参阅 [openpeon.com\u002Fcreate 上的完整指南](https:\u002F\u002Fopenpeon.com\u002Fcreate) 或 [CONTRIBUTING.md](CONTRIBUTING.md)。\n\n## 调试\n\n当声音无法播放或通知未出现时，结构化的调试日志可以帮助您追踪钩子调用过程中究竟发生了什么。\n\n### 启用调试日志\n\n```bash\npeon debug on             # 启用——日志写入 ~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Flogs\u002F\npeon debug off            # 禁用\npeon debug status         # 显示状态、日志目录、文件数量、总大小\n```\n\n您也可以通过设置环境变量 `PEON_DEBUG=1` 来在不更改配置的情况下为每次调用启用调试日志。\n\n### 阅读日志\n\n```bash\npeon logs                 # 今日日志的最后 50 行\npeon logs --last 100      # 所有日志文件中的最后 100 行\npeon logs --session \u003CID>  # 按会话 ID 筛选今日日志\npeon logs --session \u003CID> --all  # 在所有日志文件中搜索会话 ID\npeon logs --clear         # 删除所有日志文件（需确认）\n```\n\n### 日志格式\n\n每条日志都是一个结构化的键值记录：\n\n```\n2026-03-26T14:32:01.042 [config] inv=a3f1 loaded=\u002Fpath\u002Fto\u002Fconfig.json volume=0.5 pack=peon enabled=True\n2026-03-26T14:32:01.045 [event] inv=a3f1 hook_event=Stop cesp=task.complete session=abc123\n2026-03-26T14:32:01.048 [sound] inv=a3f1 file=work-work.wav label=\"Work, work.\" category=task.complete\n2026-03-26T14:32:01.120 [play] inv=a3f1 player=afplay file=work-work.wav\n2026-03-26T14:32:01.125 [notify] inv=a3f1 title=\"peon: done\" body=\"Work, work.\"\n```\n\n- **inv** — 唯一的 4 字符调用 ID，用于链接单次钩子调用的所有阶段\n- **阶段**：`[config]`、`[event]`、`[sound]`、`[play]`、`[notify]`——分别代表钩子流程中的各个阶段\n- 包含空格或特殊字符的值会被引号括起来\n\n### 常见故障示例\n\n| 症状 | 日志中应查找的内容 |\n|---|---|\n| 没有声音播放 | `[event]` 行显示 `exit=early`（分类被禁用、暂停或被去抖动） |\n| 使用了错误的声音包 | `[config]` 行显示意外的 `pack=` 值——检查路径规则或轮换设置 |\n| 缺少声音文件 | `[sound]` 行显示 `error=` 并附带文件路径 |\n| 通知缺失 | 缺少 `[notify]` 行——检查配置中的 `desktop_notifications` |\n\n### 配置键\n\n| 键 | 默认值 | 描述 |\n|---|---|---|\n| `debug` | `false` | 启用结构化调试日志记录 |\n| `debug_retention_days` | `7` | 自动清除超过 N 天的日志 |\n\n日志存储在 `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002Flogs\u002Fpeon-ping-YYYY-MM-DD.log`（每天一个文件）。当创建新一天的日志时，旧日志会根据 `debug_retention_days` 自动被清除。\n\n## 卸载\n\n**macOS\u002FLinux：**\n\n```bash\nbash \"${CLAUDE_CONFIG_DIR:-$HOME\u002F.claude}\"\u002Fhooks\u002Fpeon-ping\u002Funinstall.sh        # 全局\nbash .claude\u002Fhooks\u002Fpeon-ping\u002Funinstall.sh           # 项目本地\n```\n\n**Windows（PowerShell）：**\n\n```powershell\n# 标准卸载（删除音效前会提示）\npowershell -File \"$env:USERPROFILE\\.claude\\hooks\\peon-ping\\uninstall.ps1\"\n\n# 保留音效包（移除其他所有内容）\npowershell -File \"$env:USERPROFILE\\.claude\\hooks\\peon-ping\\uninstall.ps1\" -KeepSounds\n```\n\n## 要求\n\n- **macOS** — `afplay`（内置），JXA Cocoa 叠加层或 AppleScript 用于通知\n- **Linux** — 以下之一：`pw-play`、`paplay`、`ffplay`、`mpv`、`play`（SoX）或 `aplay`；`notify-send` 用于通知\n- **Windows** — 原生 PowerShell，配备 `MediaPlayer` 和 WinForms（无需 WSL），或 WSL2\n- **MSYS2 \u002F Git Bash** — `python3`、`cygpath`（内置）；音频可通过 `ffplay`\u002F`mpv`\u002F`play` 或 PowerShell 备用方案实现\n- **所有平台** — `python3`（Windows 原生版本除外）\n- **SSH\u002F远程** — 远程主机上需安装 `curl`\n- **IDE** — 支持钩子的 Claude Code、Amp，或通过 [适配器](#multi-ide-support) 支持的任何 IDE\n\n## 工作原理\n\n`peon.sh` 是一个注册了 `SessionStart`、`SessionEnd`、`SubagentStart`、`Stop`、`Notification`、`PermissionRequest`、`PostToolUseFailure` 和 `PreCompact` 事件的 Claude Code 钩子。每次触发事件时：\n\n1. **事件映射** — 内嵌的 Python 代码块将钩子事件映射到 [CESP](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fopenpeon) 音效类别（如 `session.start`、`task.complete`、`input.required` 等）。\n2. **音效选择** — 从当前激活的音效包清单中随机选取一条语音，避免重复。\n3. **音频播放** — 通过 `afplay`（macOS）、PowerShell 的 `MediaPlayer`（WSL2\u002FMSYS2 备用方案）或 `pw-play`\u002F`paplay`\u002F`ffplay`\u002F`mpv`\u002F`aplay`（Linux\u002FMSYS2）异步播放音效。\n4. **通知** — 更新终端标签页标题，并在终端未聚焦时发送桌面通知。\n5. **远程路由** — 在 SSH 会话、Devcontainers 和 Codespaces 中，音频和通知请求会通过 HTTP 转发到您本地机器上的 [中继服务器](#remote-development-ssh--devcontainers--codespaces)。\n\n音效包会在安装时从 [OpenPeon 注册表](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fregistry) 下载。官方音效包托管在 [PeonPing\u002Fog-packs](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fog-packs) 中。音效文件归各自发行方（Blizzard、Valve、EA 等）所有，仅以合理使用原则分发，用于个人通知目的。\n\n## 链接\n\n- [@peonping on X](https:\u002F\u002Fx.com\u002Fpeonping) — 最新动态与公告\n- [peonping.com](https:\u002F\u002Fpeonping.com\u002F) — 项目主页\n- [openpeon.com](https:\u002F\u002Fopenpeon.com\u002F) — CESP 规范、音效包浏览器、[集成指南](https:\u002F\u002Fopenpeon.com\u002Fintegrate)、创作指南\n- [OpenPeon 注册表](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fregistry) — 音效包注册表（GitHub Pages）\n- [og-packs](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fog-packs) — 官方音效包\n- [peon-pet](https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-pet) — macOS 桌面宠物（兽人精灵，对钩子事件作出反应）\n- [许可证（MIT）](LICENSE)\n\n## 支持本项目\n\n- Venmo：[@garysheng](https:\u002F\u002Fvenmo.com\u002Fgarysheng)\n- 社区代币（自行研究\u002F自娱自乐）：有人在 Base 上创建了 $PEON 代币——我们从中获得交易手续费，用于支持开发。[`0xf4ba744229afb64e2571eef89aacec2f524e8ba3`](https:\u002F\u002Fdexscreener.com\u002Fbase\u002F0xf4bA744229aFB64E2571eef89AaceC2F524e8bA3)","# Peon-Ping 快速上手指南\n\nPeon-Ping 是一款专为 AI 编程助手（如 Claude Code、Cursor、GitHub Copilot 等）设计的通知工具。当 AI 完成任务、需要权限或报错时，它会播放经典游戏语音（如魔兽、星际、传送门等）并显示屏幕横幅，帮助你保持专注流。\n\n## 环境准备\n\n### 系统要求\n支持以下操作系统：\n- **macOS**\n- **Linux** (包括 WSL2)\n- **Windows** (包括 MSYS2)\n- **SSH \u002F DevContainers \u002F Codespaces** (远程开发环境)\n\n### 前置依赖\n- **WSL2\u002FDebian 用户注意**：若使用非 WAV 格式的音效包，必须安装 `ffmpeg`。\n  ```bash\n  sudo apt update && sudo apt install -y ffmpeg\n  ```\n- **Nix 用户**：无需额外依赖，可直接通过 Nix 运行。\n\n## 安装步骤\n\n推荐根据你的系统选择以下一种方式安装：\n\n### 方式 1：Homebrew (推荐 macOS\u002FLinux 用户)\n```bash\nbrew install PeonPing\u002Ftap\u002Fpeon-ping\n```\n安装完成后，运行以下命令注册钩子并下载默认音效包：\n```bash\npeon-ping-setup\n```\n\n### 方式 2：一键脚本 (macOS, Linux, WSL2)\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.sh | bash\n```\n\n### 方式 3：PowerShell (Windows 用户)\n在 PowerShell 中运行：\n```powershell\nInvoke-WebRequest -Uri \"https:\u002F\u002Fraw.githubusercontent.com\u002FPeonPing\u002Fpeon-ping\u002Fmain\u002Finstall.ps1\" -UseBasicParsing | Invoke-Expression\n```\n*默认安装魔兽、星际、传送门三个精选包。如需自定义安装包，可访问官网交互选择。*\n\n### 方式 4：Nix (macOS, Linux)\n直接运行（无需安装）：\n```bash\nnix run github:PeonPing\u002Fpeon-ping -- status\n```\n或安装到用户配置：\n```bash\nnix profile install github:PeonPing\u002Fpeon-ping\n```\n\n## 基本使用\n\n安装完成后，Peon-Ping 会自动集成到支持的 AI 工具中。以下是常用操作：\n\n### 1. 验证状态\n检查服务是否正常运行及当前配置：\n```bash\npeon status\n```\n查看详细状态（包含通知设置、耳机检测等）：\n```bash\npeon status --verbose\n```\n\n### 2. 临时静音\u002F恢复\n在会议或结对编程时需要暂时关闭通知：\n```bash\n# 暂停通知\npeon pause\n\n# 恢复通知\npeon resume\n```\n或在 Claude Code 中直接使用斜杠命令：\n```text\n\u002Fpeon-ping-toggle\n```\n\n### 3. 管理音效包\n查看已安装的音效包：\n```bash\npeon packs list\n```\n切换音效包（例如切换到 GLaDOS 语音）：\n```bash\npeon packs use glados\n```\n浏览并安装更多音效包：\n```bash\npeon packs list --registry\npeon packs install \u003C包名>\n```\n\n### 4. 调节音量\n查看当前音量：\n```bash\npeon volume\n```\n设置音量（0.0 到 1.0）：\n```bash\npeon volume 0.7\n```\n\n### 5. 触发测试\n发送一条测试通知以确认配置生效：\n```bash\npeon notifications test\n```\n\n### 典型工作流\n1. 启动你的 AI 编程助手（如 `claude` 或 `cursor`）。\n2. 当 AI 开始工作时，你会听到 *\"Ready to work?\"*。\n3. 当任务完成时，听到 *\"Work, work.\"* 并看到屏幕横幅。\n4. 若 AI 需要输入，会播放提示音提醒你切换窗口。","资深后端工程师李明正在使用 Claude Code 重构一个遗留的微服务模块，该任务涉及大量代码生成与依赖修复，预计耗时数小时且需人工确认关键决策。\n\n### 没有 peon-ping 时\n- **频繁无效检查**：李明不敢离开终端去处理邮件或开会，每隔几分钟就要切回窗口查看 AI 是否卡住或已完成，严重打断心流。\n- **错过关键交互**：当 AI 遇到权限请求或模糊逻辑需要人类确认时，因无人响应而长时间空转，浪费宝贵的计算资源和等待时间。\n- **上下文丢失成本高**：一旦因分心未及时响应导致任务暂停，重新回顾代码逻辑和 AI 思路往往需要额外 15 分钟来恢复状态。\n- **远程开发盲区**：在通过 SSH 连接远程服务器开发时，缺乏直观的视觉或听觉反馈，完全无法感知后台 Agent 的运行状态。\n\n### 使用 peon-ping 后\n- **听觉状态感知**：peon-ping 在 AI 开始工作、完成任务或需要确认时，分别播放《魔兽争霸》中苦力\"Work work\"、\"Job done\"或警示语音，李明无需看屏即可掌握进度。\n- **即时响应机制**：当 AI 发出特定语音提示需要决策时，李明能立即从其他工作中切换回来处理，确保开发流程零延迟衔接。\n- **沉浸式大屏提醒**：屏幕上同步弹出醒目的游戏风格横幅（如星际争霸风格），即使戴着降噪耳机也能通过视觉余光捕捉到关键通知。\n- **多环境无缝覆盖**：无论是在本地 macOS、WSL2 还是远程 SSH 会话中，peon-ping 都能稳定推送通知，彻底消除远程开发的“黑盒”焦虑。\n\npeon-ping 通过将枯燥的终端状态转化为生动的游戏化音画反馈，让开发者从“看守终端”的琐事中解放，真正实现人机协作的流畅心流。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FPeonPing_peon-ping_cecac425.png","PeonPing","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FPeonPing_d897ec62.png","",null,"peonping.com","https:\u002F\u002Fgithub.com\u002FPeonPing",[79,83,87,91,95,99],{"name":80,"color":81,"percentage":82},"Shell","#89e051",49.2,{"name":84,"color":85,"percentage":86},"PowerShell","#012456",36.2,{"name":88,"color":89,"percentage":90},"TypeScript","#3178c6",8,{"name":92,"color":93,"percentage":94},"JavaScript","#f1e05a",5.3,{"name":96,"color":97,"percentage":98},"Nix","#7e7eff",0.8,{"name":100,"color":101,"percentage":102},"Swift","#F05138",0.4,4441,313,"2026-04-13T13:20:30","MIT","Linux, macOS, Windows","无 GPU 需求","未说明",{"notes":111,"python":109,"dependencies":112},"该工具主要用于播放游戏语音和显示通知，不涉及 AI 模型推理。在 WSL2 或 Debian 系 Linux 上若使用非 WAV 格式音效包，必须安装 ffmpeg。支持通过 Homebrew、安装脚本、PowerShell 或 Nix 进行安装。",[113],"ffmpeg (WSL2\u002FLinux 非 WAV 格式必需)",[15,14,13],[116,117,118,119,120,121,122,123],"ai","ai-engineering","antigravity","claude-code","codex","cursor","opencode","terminal","2026-03-27T02:49:30.150509","2026-04-14T03:09:52.632205",[127,132,137,142,147,152],{"id":128,"question_zh":129,"answer_zh":130,"source_url":131},32314,"在 Windows 上安装后，OpenCode 桌面应用或 CLI 没有声音输出怎么办？","请按以下步骤排查：\n1. 验证音频核心功能：在 PowerShell 中运行 `peon --preview session.start`。如果此时有声音，说明核心安装正常，问题出在 OpenCode 插件集成上；如果没有声音，则是 Windows 音频设备问题。\n2. 检查插件加载：查看 OpenCode 开发者控制台或日志中是否有 peon-ping 的输出，确认插件是否被实际调用。\n3. 尝试切换音频后端：Windows 默认播放器有时会有问题，可运行 `peon config audio_backend powershell` 切换到 PowerShell 后端。\n4. 已知问题：如果您使用了 WSL，尝试禁用 WSL 的 Windows 音频回放功能，这可能会解决冲突。","https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fissues\u002F367",{"id":133,"question_zh":134,"answer_zh":135,"source_url":136},32315,"使用 Nix Home Manager 安装后，为什么 Hooks 和 Skills 没有自动配置？","Nix Home Manager 模块目前仅安装二进制文件和配置文件，不会自动注册 Claude Code 的 Hooks。您需要手动配置：\n1. 参考官方文档中关于手动连接 IDE Hooks 的说明（通常涉及将 hook 脚本复制到 `~\u002F.claude\u002Fhooks\u002Fpeon-ping\u002F` 并在 `settings.json` 中注册）。\n2. 或者参考社区提供的 Nix 配置示例（如 clemenscodes 的配置），通过 `home.file` 声明式地管理 hook 脚本和设置条目。\n3. 对于 Cursor 编辑器，新的适配器已改进了 `peon.sh` 的查找链，使其能在无 `~\u002F.claude` 目录的 Nix 环境中工作。","https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fissues\u002F302",{"id":138,"question_zh":139,"answer_zh":140,"source_url":141},32316,"通过 Homebrew 安装后，OpenCode 适配器忽略 `default_pack` 配置仍使用旧版 `active_pack` 逻辑？","这是因为 Homebrew tap 中的公式版本滞后，导致安装的适配器文件过旧。解决方法如下：\n1. 更新 Homebrew tap 并升级软件：运行 `brew update && brew upgrade peon-ping`。\n2. 重新运行设置命令：执行 `peon-ping-setup` 以生成最新的适配器文件。\n3. 验证配置：确保生成的 `~\u002F.config\u002Fopencode\u002Fplugins\u002Fpeon-ping.ts` 中包含 `default_pack` 字段，且逻辑为 `const activePack = config.default_pack || config.active_pack || \"peon\"`。\n如果自动更新失败，可能需要等待维护者手动推送公式更新，或手动替换适配器文件为仓库中的最新版本。","https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fissues\u002F380",{"id":143,"question_zh":144,"answer_zh":145,"source_url":146},32317,"如何在 Windows 系统上使用 Peon Ping？","目前原生 Windows 支持有限，主要推荐以下方案：\n1. 使用 WSL (Windows Subsystem for Linux)：这是目前最稳定的方式，但需注意 WSL 可能无法自动检测 Windows 上的 Claude Code 安装路径，可能需要手动配置路径或使用特定的安装脚本。\n2. 避免直接使用纯 Bash 脚本：由于项目主要基于 Bash，直接在 CMD 或 PowerShell 运行可能会遇到兼容性问题。\n3. 社区建议：如果有强烈需求，可以考虑寻找或开发纯 Python 实现的 Fork 版本以获得更好的跨平台支持，但在官方完全支持前，WSL 仍是首选方案。","https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fissues\u002F46",{"id":148,"question_zh":149,"answer_zh":150,"source_url":151},32318,"在 Windows (Git Bash) 下安装特定音效包（如 solid_snake）时提示“Failed to download manifest”怎么办？","这通常是由于 Windows 环境下网络请求或路径解析问题导致的。建议尝试：\n1. 切换安装环境：尽量避免在 Git Bash\u002FMINGW64 中直接运行安装命令，尝试在原生的 PowerShell 中运行安装脚本。\n2. 检查网络连接：确保能够访问音效包的托管服务器（manifest 文件地址）。\n3. 手动下载：如果自动安装持续失败，可以尝试手动下载 pack 文件并放置到 `~\u002F.openpeon\u002Fpacks` 目录下。\n4. 更新工具：确保 `peon-ping` 本身已更新到最新版本，以获取针对 Windows 环境的修复补丁。","https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fissues\u002F343",{"id":153,"question_zh":154,"answer_zh":155,"source_url":131},32319,"如何验证 Peon Ping 是否正确安装并能播放声音？","可以使用内置的预览命令进行快速验证，无需触发实际的 AI 任务：\n1. 打开终端（Windows 用户使用 PowerShell，Mac\u002FLinux 使用 Bash\u002FZsh）。\n2. 运行命令：`peon --preview session.start`（也可以替换为 `task.complete` 等其他事件类型）。\n3. 观察结果：\n   - 如果听到声音：说明核心程序和音频后端工作正常。如果此时在 IDE 中没声音，问题在于 IDE 插件未正确加载或 Hook 未触发。\n   - 如果没声音：说明是底层音频设备、权限或安装路径问题，需检查系统音量、输出设备选择或重新安装。",[157,162,167,172,177,182,187,192,197,202,207,212,217,222,227,232,237,242,247,252],{"id":158,"version":159,"summary_zh":160,"released_at":161},247107,"v2.18.0","## 变更内容\n* 修复 shell 脚本缺少执行权限的问题，由 @paskal 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F423 中完成\n* Windows 平台的 MP3 音频包更新，由 @Dirrik 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F425 中完成\n* 重构：将 OpenCode 适配器改造成一个通过 peon.sh 进行路由的轻量封装层，由 @ImBIOS 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F430 中完成\n* 修复：在内部使用 PEON_PLATFORM 变量以避免与环境变量 $PLATFORM 冲突（#426），由 @garysheng 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F431 中完成\n* 修复：移除 trainer 子 shell 中函数外部使用的 `local` 关键字，由 @ImBIOS 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F435 中完成\n* 修复：为 Windows 版本的 peon.ps1 添加 SessionStart 防抖功能，实现与 peon.sh 的对齐，由 @kegechen 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F433 中完成\n* 修复：防止 WinForms 叠加窗口在 WSL\u002FMSYS2 上抢夺焦点，由 @garysheng 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F436 中完成\n* 修复：将 Python 代码写入临时文件以规避 MSYS2 的 ARG_MAX 限制，由 @garysheng 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F437 中完成\n* 修复：当 ffmpeg 缺失时发出警告，并回退到默认音量，由 @garysheng 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F438 中完成\n* 修复：修正 SessionStart 防抖冷却时间中的 PowerShell 真值逻辑错误，由 @garysheng 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F440 中完成\n* 新特性：TTS 配置模式及更新补全操作，由 @garysheng 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F442 中完成\n* 新特性：新增随机轮换模式，由 @rursache 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F444 中完成\n* 修复：限制标准输入读取，以防止在 Windows Git Bash 上出现卡死现象，由 @garysheng 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F447 中完成\n* 新特性：添加 --lang 标志，可在安装过程中按语言筛选音频包，由 @fabio-andre-rodrigues 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F450 中完成\n\n## 新贡献者\n* @Dirrik 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F425 中完成了首次贡献\n* @ImBIOS 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F430 中完成了首次贡献\n* @kegechen 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F433 中完成了首次贡献\n* @rursache 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F444 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.17.3...v2.18.0","2026-04-11T15:29:44",{"id":163,"version":164,"summary_zh":165,"released_at":166},247108,"v2.17.3","## 变更内容\n* 由 @paskal 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F419 中添加了原生 zsh 补全文件\n* 修复：在 Windows 的 prune 测试中使用相对日期，由 @ctsstc 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F420 中完成\n* 新增功能：notification_all_screens 配置 + 基于事件的覆盖层关闭功能，由 @ctsstc 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F416 中实现\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.17.2...v2.17.3","2026-03-31T11:01:25",{"id":168,"version":169,"summary_zh":170,"released_at":171},247109,"v2.17.2","## 变更内容\n* 修复：@ctsstc 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F415 中为 iTerm2 的覆盖式通知修复了点击聚焦问题。\n* 修复：@eddienubes 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F418 中添加了 wezterm 的 Bundle ID。\n\n## 新贡献者\n* @eddienubes 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F418 中完成了首次贡献。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.17.1...v2.17.2","2026-03-30T01:50:54",{"id":173,"version":174,"summary_zh":175,"released_at":176},247110,"v2.17.1","## 变更内容\n* 功能：Windows 训练器 — CLI 子命令、钩子提醒以及 Pester 测试，由 @muunkky 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F393 中实现\n* 功能：Windows 的通知模板解析，由 @muunkky 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F398 中实现\n* 修复：通过 SubagentStop 钩子抑制子代理声音，由 @aletar89 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F399 中实现\n* 文档：添加日文 README，由 @eltociear 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F401 中实现\n* 功能：Windows 通知 CLI、模板函数以及 README_zh 翻译，由 @muunkky 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F400 中实现\n* 文档：PRD-002 — 钩子可观性与结构化日志记录，由 @muunkky 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F403 中实现\n* 钩子执行的结构化调试日志记录，由 @muunkky 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F405 中实现\n* 修复：在全局安装过程中安装 peon PATH shim，由 @Audacity88 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F409 中实现\n* 修复：在主题叠加层中尊重 notification_position 配置，由 @ctsstc 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F413 中实现\n* 修复：在钩子中因 \u002Fdev\u002Ftty 重定向失败时抑制 bash 标准错误泄漏，由 @garysheng 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F414 中实现\n\n## 新贡献者\n* @aletar89 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F399 中完成了首次贡献\n* @eltociear 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F401 中完成了首次贡献\n* @Audacity88 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F409 中完成了首次贡献\n* @ctsstc 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F413 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.16.1...v2.17.1","2026-03-29T10:51:48",{"id":178,"version":179,"summary_zh":180,"released_at":181},247111,"v2.16.1","**完整更新日志**: https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.16.0...v2.16.1","2026-03-20T09:43:47",{"id":183,"version":184,"summary_zh":185,"released_at":186},247112,"v2.16.0","## 变更内容\n* 修复：通过活动终端更精确地抑制 Ghostty 通知，由 @Sogl 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F382 中完成\n* 新功能：在 Windows 上使用带音量控制的 MediaPlayer 播放 WAV 文件，由 @ForNeVeR 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F381 中完成\n* 修复：在 rovodev 钩子安装程序中保留多行 YAML 命令值，由 @jamiecwilliams 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F384 中完成\n\n## 新贡献者\n* @ForNeVeR 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F381 中完成了首次贡献\n* @jamiecwilliams 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F384 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.15.2...v2.16.0","2026-03-20T03:33:06",{"id":188,"version":189,"summary_zh":190,"released_at":191},247113,"v2.15.2","## 变更内容\n* 修复：在预览中尊重 linux_audio_player 和 ssh_audio_mode，由 @cstrahan 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F346 中完成\n* 文档：为 Kiro 设置配置添加缺失的 'name' 字段，由 @carlfugate 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F349 中完成\n* 修复 aplay 对非 WAV 文件的使用问题（支持 MP3\u002FOGG），由 @sjhddh 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F354 中完成\n* 功能：新增 --rovodev-only 标志，用于 homebrew 委托，由 @Foxh0und 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F352 中完成\n* 功能（Nix）：在 installPacks 中支持自定义包源，由 @isbecker 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F356 中完成\n* 修复：下载清单文件中引用的包图标资源，由 @Sogl 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F357 中完成\n* 修复具有相同显示名称的包问题，由 @batzorigco 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F359 中完成\n* 修复：在 tmux 会话中支持 iTerm2 标签页颜色和标题，由 @ghkdxofla 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F360 中完成\n* 修复：为 --local 安装注册项目级设置中的钩子，由 @htetyan 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F362 中完成\n* 修复：在非交互式 Claude 会话中静音，由 @pindab0ter 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F364 中完成\n* 冲刺\u002FHOOKBUG：修复 Windows 钩子死锁及原子状态写入问题，由 @muunkky 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F363 中完成\n* 冲刺\u002FSMARTPACK：通过 path_rules 实现按项目分配包，由 @muunkky 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F365 中完成\n* 修复：在 Linux 上为会议检测添加 pactl 备用方案，由 @DmitrySandalov 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F372 中完成\n* 扩展 README 中关于 Codex 的说明，由 @zkendall 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F376 中完成\n* 杂项：在 peon CLI 命令中跳过冗余的配置写入，由 @muunkky 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F374 中完成\n* 冲刺\u002FSMARTPACKDEBT：解决 SMARTPACK 冲刺评审中遗留的技术债务，由 @muunkky 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F366 中完成\n* 修复：在工具使用事件中清除 needs_approval 标签页的颜色，由 @ilganeli 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F377 中完成\n* 冲刺\u002FWINTEST：Windows Pester 测试套件，跨平台加固，由 @muunkky 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F375 中完成\n\n## 新贡献者\n* @cstrahan 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F346 中完成了首次贡献\n* @carlfugate 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F349 中完成了首次贡献\n* @sjhddh 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F354 中完成了首次贡献\n* @isbecker 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F356 中完成了首次贡献\n* @batzorigco 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F359 中完成了首次贡献\n* @ghkdxofla 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F360 中完成了首次贡献\n* @pindab0ter 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F364 中完成了首次贡献\n* @muunkky 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F363 中完成了首次贡献\n* @DmitrySandalov 完成了","2026-03-19T12:23:29",{"id":193,"version":194,"summary_zh":195,"released_at":196},247114,"v2.15.1","## 变更内容\n* 修复：Rovo Dev CLI 安装程序现在能够正确处理空的事件数组，并新增 IDE 检测功能，由 @Foxh0und 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F324 中实现。\n* 修复：Relay 现在使用正确的包和图标，而非硬编码的 Peon 默认值，由 @choutianxius 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F326 中实现。\n* 修复：防止 \u002Fpeon-ping-rename 在同一项目的不同标签页之间产生干扰，由 @garysheng 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F328 中实现。\n* 修复：Relay 通知现在使用包中的图标，而非硬编码的 Peon 默认图标，由 @choutianxius 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F329 中实现。\n* 修复：为 Cursor IDE 的 beforeSubmitPrompt 注册 hook-handle-rename.sh 脚本，由 @stuctf 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F331 中实现。\n* 在 Peon 状态的 IDE 列表中新增 OpenAI Codex 检测功能，由 @KyloJorgensen 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F332 中实现。\n* 修复：避免在通知测试命令中出现 zsh 警告，由 @0xsline 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F334 中实现。\n* 新特性：添加 DeepAgents 适配器，由 @jkennedyvz 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F327 中实现。\n* 文档更新：将 DeepAgents 添加到 llms.txt 文件中，由 @jkennedyvz 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F335 中完成。\n* 修复：MSYS2 音频播放问题——去除 CRLF、设置 PYTHONUTF8 环境变量，并下载 win-play.ps1 脚本，由 @garysheng 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F338 中实现。\n* 修复：通过 TTY walk 方法隔离终端标签页中的 \u002Fpeon-ping-rename 命令，由 @bdon-jane 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F341 中实现。\n* 修复：将语义通知类型传递给叠加主题（jarvis、glass、sakura），由 @joshblease 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F342 中实现。\n\n## 新贡献者\n* @KyloJorgensen 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F332 中完成了首次贡献。\n* @0xsline 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F334 中完成了首次贡献。\n* @jkennedyvz 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F327 中完成了首次贡献。\n* @joshblease 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F342 中完成了首次贡献。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.15.0...v2.15.1","2026-03-09T13:39:49",{"id":198,"version":199,"summary_zh":200,"released_at":201},247115,"v2.15.0","## 变更内容\n* 功能新增：新增 `peon packs rotation clear` 命令，由 @bandrel 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F322 中实现。\n\n## 新贡献者\n* @bandrel 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F322 中完成了首次贡献。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.14.0...v2.15.0","2026-03-06T18:23:45",{"id":203,"version":204,"summary_zh":205,"released_at":206},247116,"v2.14.0","## 变更内容\n* 修复：添加 Shell 监视器，以防止 macOS 上出现孤立的 overlay 进程，由 @garysheng 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F305 中实现\n* 屏蔽子代理的 PermissionRequest 通知，由 @josejimenezjr0 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F307 中实现\n* 添加说明，指出在 Windows 的 WSL2 环境中需要安装 ffmpeg，由 @rprouse 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F309 中实现\n* 增加了按终端会话自定义标题的功能，不再为每个项目固定一个标题，由 @bdon-jane 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F310 中实现\n* 修复：在计划模式下以及执行 \u002Fclear 命令后，\u002Fpeon-ping-rename 标题会恢复默认值的问题，由 @bdon-jane 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F316 中修复\n* 功能\u002F中继状态推送，由 @dieterpl 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F314 中实现\n* Atlassian RovoDev 适配器，由 @Foxh0und 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F317 中实现\n* 新增功能：添加可配置的 SSH 音频路由模式，由 @pandego 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F319 中实现\n* Home Manager：光标钩子与适配器修复，提升软件包安装的可重复性，由 @PierreBeucher 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F315 中实现\n\n## 新贡献者\n* @josejimenezjr0 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F307 中完成了首次贡献\n* @rprouse 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F309 中完成了首次贡献\n* @bdon-jane 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F310 中完成了首次贡献\n* @dieterpl 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F314 中完成了首次贡献\n* @Foxh0und 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F317 中完成了首次贡献\n* @pandego 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F319 中完成了首次贡献\n* @PierreBeucher 在 https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F315 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.12.1...v2.14.0","2026-03-06T09:33:33",{"id":208,"version":209,"summary_zh":210,"released_at":211},247117,"v2.12.1","## What's Changed\n* fix: themed overlays ignore notification_dismiss_seconds=0 by @tom-price in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F291\n* fix: resolve Windows install failures (#292) by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F293\n* video: wc2_human_ships preview by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F294\n* video: wc2_sapper preview by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F295\n* Update pack counts and add Chinese language filter by @AlexZhangji in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F296\n* feat: add mute\u002Funmute as aliases for pause\u002Fresume by @taylan in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F297\n* fix: don't mark adapter threads idle during cooldown by @stuctf in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F300\n* fix: kill orphaned mac-overlay processes on SessionEnd by @stuctf in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F301\n\n## New Contributors\n* @tom-price made their first contribution in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F291\n* @AlexZhangji made their first contribution in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F296\n* @taylan made their first contribution in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F297\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.12.0...v2.12.1","2026-03-02T20:39:39",{"id":213,"version":214,"summary_zh":215,"released_at":216},247118,"v2.12.0","## What's Changed\n* fix(win): Cursor on Windows — BOM handling, camelCase events, flat-array hooks.json by @dlavati in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F236\n* feat(cli): add peon packs rotation subcommands by @bretta-seerist in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F235\n* Feat\u002Fgemini cli by @ralfun11 in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F224\n* fix(win): make ps1 peon --volume mirror sh version behavior by @dlavati in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F237\n* feat(cli): add peon packs install-local command by @choutianxius in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F238\n* fix: guard completions.bash for non-interactive shells by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F241\n* fix(win): locale-safe config, --volume mirror sh, repair bad config on install by @dlavati in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F242\n* chore: add Nix flake for development and installation by @andreabadesso in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F243\n* fix(preview): respect use_sound_effects_device from config by @Sogl in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F244\n* fix: add missing gemini and openclaw adapters to install.sh by @klava-spark-dev in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F245\n* feat: add declarative relay service for NixOS and nix-darwin by @andreabadesso in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F247\n* feat: add MSYS2 \u002F Git Bash platform support by @kvnxiao in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F246\n* feat: iTerm2 multi-window\u002Ftab focus + overlay themes by @hn6pot in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F249\n* fix: CLI config path now matches hook read path by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F253\n* feat: add headphones_only mode for macOS, Linux, and WSL by @hugodelahousse in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F251\n* Fix iTerm2 tab focus detection with multiple windows by @tylergohl in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F256\n* feat: add Amp adapter (filesystem watcher for ampcode.com) by @MarcelloLins in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F257\n* Add suppress_sound_when_tab_focused config option by @tylergohl in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F258\n* fix(security): harden shell-to-Python handoffs, adapter JSON, atomic writes, audio allowlist by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F259\n* feat: auto-suppress sounds when microphone is active by @alexanderwait in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F262\n* fix(windows): use SoundPlayer for WAV files in hidden process by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F263\n* fix(windows): normalize PSCustomObject for session_packs in hook-handle-use.ps1 by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F265\n* Fix Windows peon packs use\u002Fnext subcommands by @fabio-andre-rodrigues in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F267\n* Update README.md with meeting_detect config value explanation by @bobber205 in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F268\n* fix: Ghostty detection with tmux and case-sensitive process name by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F270\n* fix: debounce SessionStart greeting spam from multi-workspace IDE startup by @techtoboggan in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F271\n* Feature\u002Fselective sound control by @wangke19 in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F272\n* Add ability to show custom character icon from openpeon.json schema for desktop notifications by @homich1991 in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F273\n* fix: handle nested sound dirs and special chars in filenames by @chrisvaillancourt in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F281\n* fix(windows): harden state parsing and restore reliable hook audio by @nmotlagh in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F280\n* feat: add Kimi Code CLI adapter by @GigaMax13 in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F282\n* feat: add bind\u002Funbind\u002Fbindings CLI commands for per-directory pack rules by @DanGrund in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F277\n* feat: configurable notification position, dismiss, labels, and message templates by @jackal092927 in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F260\n* fix: relay does not apply local notification position\u002Fdismiss settings by @kimdwkimdw in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F287\n* fix(opencode): filter subagent sessions from sound\u002Fnotification events by @luqs1 in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F290\n* feat: add native Windows PowerShell adapters for all 11 IDEs by @fabio-andre-rodrigues in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F285\n\n## New Contributors\n* @bretta-seerist made their first contribution in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F235\n* @choutianxius made their first contribution in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F238\n* @andreabadesso made their first contribution in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F243\n* @Sogl made their first contribution in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpu","2026-02-27T22:55:05",{"id":218,"version":219,"summary_zh":220,"released_at":221},247119,"v2.8.1","**Full Changelog**: https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.8.0...v2.8.1","2026-02-20T15:01:27",{"id":223,"version":224,"summary_zh":225,"released_at":226},247120,"v2.8.0","## What's Changed\n* fix: add Zed terminal to click-to-focus bundle ID map by @stuctf in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F227\n* refactor: extract notification logic into shared scripts\u002Fnotify.sh by @Faithfinder in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F228\n* fix(install): validate existing hook paths by @cwelsys in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F230\n* feat(config): flag to skip shell config by @cwelsys in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F229\n* docs: add Korean README (README_ko.md) by @munggo in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F234\n\n## New Contributors\n* @cwelsys made their first contribution in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F230\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.7.0...v2.8.0","2026-02-20T14:20:59",{"id":228,"version":229,"summary_zh":230,"released_at":231},247121,"v2.7.0","## What's Changed\n* feat: add path_rules, rename active_pack→default_pack, agentskill→session_override by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F225\n* feat: click-to-focus terminal on macOS notification click by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F226\n\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.6.0...v2.7.0","2026-02-19T20:00:12",{"id":233,"version":234,"summary_zh":235,"released_at":236},247122,"v2.6.0","## What's Changed\n* feat: Add Gemini CLI adapter with setup instructions, detection, and tests. by @ralfun11 in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F221\n* feat: add suppress_subagent_complete to silence sub-agent completion sounds by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F222\n* chore: bump version to 2.6.0 by @garysheng in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F223\n\n## New Contributors\n* @ralfun11 made their first contribution in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F221\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.5.0...v2.6.0","2026-02-19T17:58:38",{"id":238,"version":239,"summary_zh":240,"released_at":241},247123,"v2.5.0","**Full Changelog**: https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.4.0...v2.5.0","2026-02-18T21:26:22",{"id":243,"version":244,"summary_zh":245,"released_at":246},247124,"v2.4.0","## What's Changed\n* fix(opencode): respect desktop_notifications config setting by @stuctf in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F210\n* fix(opencode): fix Linux audio backend chain and volume scaling by @stuctf in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F211\n* Allow local config with global install by @hsearcy in https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fpull\u002F209\n\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.3.0...v2.4.0","2026-02-18T19:05:23",{"id":248,"version":249,"summary_zh":250,"released_at":251},247125,"v2.3.0","**Full Changelog**: https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.2.3...v2.3.0","2026-02-18T16:27:48",{"id":253,"version":254,"summary_zh":255,"released_at":256},247126,"v2.2.3","**Full Changelog**: https:\u002F\u002Fgithub.com\u002FPeonPing\u002Fpeon-ping\u002Fcompare\u002Fv2.2.2...v2.2.3","2026-02-18T14:47:57"]