Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
PeonPing은 AI 코딩 에이전트가 사용자에게 주의를 요청하거나 중요한 정보를 전달할 때 음성 및 시각적 알림을 제공하는 시스템입니다. 이 도구는 개발자가 집중력을 유지하며 에이전트를 효과적으로 활용하도록 돕습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기macOS WSL2 Linux Windows MSYS2 SSH
License
Claude Code Amp Gemini CLI GitHub Copilot Codex Grok Build Cursor OpenCode Kilo CLI Kiro Kimi Code Windsurf Antigravity OpenClaw Rovo Dev CLI DeepAgents oh-my-pi Qwen Code iFlow CLI Trae Kiro IDE ECA
AI 코딩 에이전트가 주의를 필요로 할 때 음성 라인과 시각적 오버레이 알림을 제공하며, 또는 에이전트가 MCP를 통해 자체 사운드를 선택하도록 합니다.
AI 코딩 에이전트는 작업 완료나 권한 요청 시 사용자에게 알리지 않습니다. 사용자는 다른 곳으로 이동하여 집중력을 잃고 다시 흐름(flow)에 진입하는 데 15분을 허비하게 됩니다. peon-ping은 Warcraft, StarCraft, Portal, Zelda 등에서 가져온 음성 라인과 눈에 띄는 화면 배너로 이를 해결합니다 — Claude Code, Amp, GitHub Copilot, Codex, Grok Build, Cursor, OpenCode, Kilo CLI, Kiro, Kimi Code, Windsurf, Google Antigravity, Rovo Dev CLI, DeepAgents, Qwen Code, iFlow CLI, Trae, Kiro IDE, ECA, 그리고 모든 MCP 클라이언트와 작동합니다.
작동 모습 보기 → peonping.com
<video src="https://github.com/user-attachments/assets/149b6d15-65c2-41f2-9b56-13575ff8364b" autoplay loop muted playsinline width="400"></video>
</div>
brew install PeonPing/tap/peon-ping
그다음 peon-ping-setup을 실행하여 훅(hooks)을 등록하고 사운드 팩을 다운로드하세요. macOS 및 Linux.
curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash
⚠️ WSL2 오디오 참고 사항. peon-ping은 Windows 측에서 오디오를 재생합니다. 첫 실행 시 최적의 재생 경로를 선택하기 위해 Windows 호스트를 한 번 조사(Windows 빌드별로 캐시됨)합니다:
Windows 10 / Windows 11 (24H2 이전): WPF MediaPlayer가 직접 사용됩니다 — 네이티브 MP3 + WAV이며, 추가 종속성이 필요 없습니다.
Windows 11 (24H2 이상) (빌드 26100+): Microsoft가 OS에서 레거시 Windows Media Player를 제거하여 WPF MediaPlayer가 실패합니다 (MILAVERR_INVALIDWMPVERSION). peon-ping은 System.Media.SoundPlayer로 폴백(fallback)하며, 이는 Win32의 PlaySound API를 사용하고 모든 곳에서 작동하지만 — WAV 전용이므로 MP3 팩을 실시간으로 트랜스코딩하려면 ffmpeg가 필요합니다:
sudo apt update; sudo apt install -y ffmpeg
다음 환경 변수를 사용하여 자동 감지 기능을 재정의할 수 있습니다: `PEON_WSL_AUDIO_BACKEND=auto|mediaplayer|soundplayer`:
- `auto` (기본값) — 위에서 설명한 대로 조사 및 캐시
- `mediaplayer` — WSL UNC 경로를 통해 WPF MediaPlayer 강제 사용 (24H2 이상에서는 조용히 실패함)
- `soundplayer` — 임시 파일 복사 + `SoundPlayer` 강제 사용 (범용적이며, 비(非)WAV 파일의 경우 ffmpeg 필요)
### 옵션 3: Windows 설치 프로그램
```powershell
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.ps1" -OutFile ".\install.ps1" -UseBasicParsing
powershell -ExecutionPolicy Bypass -File .\install.ps1
기본적으로 엄선된 스타터 팩 세트를 설치합니다. 설정을 유지하면서 업데이트하려면 재실행하세요. 또는 **peonping.com에서 대화형으로 팩을 선택**하여 사용자 지정 설치 명령을 받으세요.
Windows 설치 프로그램 매개변수:
-All — 사용 가능한 모든 팩을 설치합니다.
-Packs peon,sc_kerrigan,... — 특정 팩만 설치합니다.
-Lang en,fr,... — 언어가 일치하는 팩만 설치합니다.
-Local — 현재 프로젝트의 ./.claude/ 폴더에 팩, 설정(config), 후크(hooks), 스킬을 설치합니다.
-Global — 명시적인 전역 설치 (기본값과 동일합니다).
-InitLocalConfig — ./.claude/hooks/peon-ping/config.json 파일만 생성합니다.
-Local은 전역 peon CLI shim을 설치하거나 사용자 PATH를 수정하지 않습니다. 후크는 프로젝트 레벨의 ./.claude/settings.json에 절대 경로로 등록되어 프로젝트 내 어느 작업 디렉토리에서도 작동할 수 있습니다.
Windows 예시:
powershell -ExecutionPolicy Bypass -File .\\\install.ps1 -All
powershell -ExecutionPolicy Bypass -File .\\\install.ps1 -Packs peon,sc_kerrigan
powershell -ExecutionPolicy Bypass -File .\\\install.ps1 -Local
...
초기 다운로드 시 구형 Windows PowerShell에서 TLS 오류가 발생하면, 같은 세션에서 다음 명령을 한 번 실행하고 다시 시도하십시오:
[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
git clone https://github.com/PeonPing/peon-ping.git
cd peon-ping
./install.sh
Windows PowerShell의 경우:
git clone https://github.com/PeonPing/peon-ping.git
Set-Location peon-ping
.\\\install.ps1
설치 없이 소스에서 직접 실행:
nix run github:PeonPing/peon-ping -- status
nix run github:PeonPing/peon-ping -- packs install peon
또는 프로필에 설치:
nix profile install github:PeonPing/peon-ping
개발 셸 (bats, shellcheck, nodejs):
nix develop # 또는 direnv 사용
재현 가능한 설정을 위해 Home Manager 모듈을 사용하십시오:
# home.nix 또는 flake.nix에서
{ inputs, pkgs, ... }:
...
사운드 팩 설치: installPacks 옵션은 두 가지 형식을 지원합니다:
"peon", "glados") — og-packs 저장소에서 가져옵니다.name과 src 필드를 가진 attrset이며, 여기서 src는 모든 Nix fetcher 결과물일 수 있습니다 (예: pkgs.fetchFromGitHub).openpeon.com에 나열된 팩의 경우, GitHub 저장소 링크를 찾아 pkgs.fetchFromGitHub를 사용하세요:
{
name = "pack_name";
src = pkgs.fetchFromGitHub {
...
Claude Code hooks: programs.peon-ping.claudeCodeIntegration = true;를 설정하면 Claude Code 훅 스크립트가 ~/.claude/hooks/peon-ping/ 아래에 설치되고, 표준 peon-ping 훅 항목들이 ~/.claude/settings.json으로 병합됩니다.
기타 IDE hooks: 다른 IDE용 어댑터는 여전히 옵트인(opt-in) 방식이므로 모듈이 관련 없는 IDE 설정을 덮어쓰지 않습니다. peon-ping은 adapters/에서 cursor.sh와 같은 어댑터 스크립트를 제공하며, 다음과 같이 연결할 수 있습니다:
${inputs.peon-ping.packages.${pkgs.stdenv.hostPlatform.system}.default}/share/peon-ping/adapters/$YOUR_IDE.sh EVENT_NAME
위의 Cursor 예시를 참고하세요.
| 이벤트 | CESP 카테고리 | 예시 |
|---|---|---|
| 세션 시작 | session.start | "Ready to work!", "Something need doing?" |
| ... | ||
또한 모든 화면(macOS/WSL/MSYS2)과 터미널 탭 제목(● project: done)에 큰 오버레이 배너가 표시되어, 다른 앱을 사용하고 있더라도 무언가 발생했음을 알 수 있습니다. |
peon-ping은 Coding Event Sound Pack Specification (CESP) — 모든 에이전트 기반 IDE가 채택할 수 있는 코딩 이벤트 사운드에 대한 개방형 표준을 구현합니다.
회의나 페어링 세션 중에 소리 및 알림을 음소거해야 하나요? 두 가지 옵션이 있습니다:
| Method | 명령어 | 사용 시점 |
|---|---|---|
| 슬래시 명령어 | /peon-ping-toggle | Claude Code에서 작업 중일 때 |
| CLI | peon toggle | 모든 터미널 탭에서 |
자동으로 작동하는 것을 선호하십니까? focus_detect를 설정하여 peon-ping이 macOS의 **집중 모드 (Focus / Do Not Disturb)**를 인식하도록 하세요. 집중 모드가 활성화되면 소리 및 알림은 조용해지며, 비활성화하면 다시 작동합니다. 또한 headphones_only와 meeting_detect도 확인하세요.
다른 CLI 명령어:
Windows 참고: Windows는 현재 초기 제어 기능(
status,toggle,volume, 핵심packs,notifications on/off,debug,logs,trainer)을 지원합니다.setup,rotation,preview,mobile과 같은 더 고급 명령어는 후속 Windows 동기화 작업으로 추적되고 있습니다.
peon setup # 대화형 설정 마법사 (볼륨, 카테고리, 알림)
peon pause # 소리 음소거
peon resume # 소리 음소거 해제
...
peon preview에서 사용 가능한 CESP 카테고리: session.start, task.acknowledge, task.complete, task.error, input.required, resource.limit, user.spam. (확장된 카테고리인 session.end와 task.progress는 CESP 사양에 정의되어 있고 pack manifest에서 지원되지만, 현재 내장 후크 이벤트에 의해 트리거되지는 않습니다.)
탭 완성(Tab completion)이 지원됩니다 — 사용 가능한 pack 이름을 보려면 peon packs use <TAB>을 입력하세요.
일시 정지(Pausing)는 소리와 데스크톱 알림을 즉시 음소거합니다. 다시 시작할 때까지 세션 전반에 걸쳐 유지됩니다. 일시 정지 상태에서도 탭 제목은 활성 상태를 유지합니다.
peon setuppeon-ping을 구성하는 가장 빠른 방법은 대화형 마법사입니다:
peon setup
이것은 모든 일반적인 설정을 한 번에 안내합니다 — 현재 값을 유지하려면 어떤 프롬프트에서든 Enter를 누르세요:
╔══════════════════════════════════════╗
║ peon-ping setup wizard ║
╚══════════════════════════════════════╝
...
**위자드가 다루는 내용:**
- **볼륨(Volume)** — 재생 볼륨 (0.0 – 1.0)
- **사운드 카테고리(Sound categories)** — 각 CESP 카테고리를 개별적으로 활성화/비활성화 (세션 시작, 작업 완료, 권한 프롬프트, 오류 등)
- **데스크톱 알림(Desktop notifications)** — 오버레이 배너의 마스터 스위치
- **오버레이 테마(Overlay theme)** — 시각적 스타일 선택 (네온, 유리, 사쿠라, jarvis)
- **위치(Position)** — 알림이 표시되는 위치 (상단 중앙, 우측 상단 등)
- **자동 해제(Auto-dismiss)** — 알림이 보이는 시간 (`0` = 영구 유지, 클릭하여 해제)
설정을 완료하면 위자드가 요약본을 출력하고 모든 내용을 `~/.claude/hooks/peon-ping/config.json`에 저장합니다. 언제든지 `peon setup`을 다시 실행하여 설정을 조정할 수 있으며, 이때 항상 현재 값을 기본값으로 보여줍니다.
> **팁:** 개별 `peon` 하위 명령어들(`peon volume`, `peon notifications position top-right` 등)도 스크립팅이나 한 번에 하나의 설정만 조정하고 싶을 때 여전히 작동합니다. [빠른 제어](#quick-controls) 섹션을 참조하세요.
### 슬래시 명령어 및 수동 설정
peon-ping은 Claude Code에도 슬래시 명령어를 설치합니다:
- `/peon-ping-toggle` — 사운드 음소거/음소거 해제
- `/peon-ping-config` — 모든 설정 변경 (볼륨, 팩, 카테고리 등)
- `/peon-ping-rename <이름>` — 이 세션에 사용자 지정 이름 부여 (알림 제목 및 터미널 탭 제목에 표시됨) (토큰 0개, 후크 가로채기); 인자 없음은 자동 감지로 초기화