PeonPing/peon-ping

peon‑ping – AI 코딩 어시스턴트를 위한 오디오 및 시각적 신호

무엇인가요 – peon‑ping는 AI 기반 코딩 어시스턴트(Claude Code, GitHub Copilot, Cursor 등)에 연결되는 가벼운 보조 도구입니다. 어시스턴트가 작업을 완료했을 때, 권한이 필요할 때, 오류가 발생했을 때, 또는 기타 주목할 만한 이벤트가 발생하면 짧은 음성 라인(대부분 Warcraft 또는 Portal 같은 게임의 멤 버전 대사)을 재생하고 강조된 화면 내 배너를 표시합니다. 목적은 터미널이나 IDE를 계속 주시하지 않아도 작업 흐름을 유지할 수 있도록 하는 것입니다.

작동 방식 – 이 프로젝트는 작은 CLI(peon)와 지원되는 어시스턴트가 핵심 순간에 호출하는 훅을 제공합니다. 이러한 훅은 Coding Event Sound Pack Specification (CESP) 를 호출하여 task.complete 또는 input.required와 같은 이벤트를 사운드 팩에 저장된 오디오 파일에 매핑합니다. CLI는 또한 다음 기능을 관리합니다:

• 사운드 팩 설치 및 전환(커뮤니티 기여 팩 포함).
• 볼륨 조절, 음성 카테고리의 활성화 여부, 데스크톱 오버레이 표시 여부 제어.
• WSL2, SSH, devcontainers와 같은 원격 개발 환경에서 오디오 리레이 데몬을 통한 통합.
• 무료 ntfy 서비스를 통한 선택적 모바일 푸시 알림.

주요 기능

기능	제공되는 기능
광범위한 어시스턴트 지원	Claude Code, Amp, GitHub Copilot, Codex, Cursor, Kiro, Qwen Code 등 다수의 어시스턴트용 사전 제작된 어댑터.
크로스 플랫폼	macOS, Linux, Windows, WSL2, MSYS2 – 오디오 재생은 자동으로 적응(Windows Presentation Foundation MediaPlayer, PlaySound, 또는 ffmpeg 변환된 WAV).
사운드 팩	게임 캐릭터(예: GLaDOS, Kerrigan)를 테마로 한 사전 제작된 팩과 커뮤니티 팩 레지스트리. 팩은 설치, 프로젝트에 바인딩, 자동 회전 가능.
시각 오버레이	어떤 화면에도 표시되는 대규모 사용자 정의 배너(네온, 글래스, 사쿠라, Jarvis) 및 터미널 탭 제목 업데이트.
CLI 제어	peon toggle, peon volume 0.7, peon packs install …, peon preview 등. 모든 명령어는 탭 완성 지원.
집중 모드에 따른 음소거	macOS의 "방해 금지" 모드 또는 헤드셋 감지 시 음성 자동 음소거 옵션.
원격 개발 지원	오디오 리레이 데몬이 컨테이너/SSH 세션의 사운드를 호스트 머신으로 전달.
모바일 알림	무료 ntfy를 통한 푸시 알림; peon mobile ntfy <topic>로 설정 가능.
확장 가능한 설정	~/.claude/hooks/peon-ping/ (또는 프로젝트 로컬 .claude/)에 JSON 형식으로 저장. 인터랙티브 peon setup 워즈드도 제공.

일반적인 워크플로우

1. Homebrew, 제공된 스크립트, 또는 Nix를 통해 설치.
2. peon setup 실행 – 볼륨, 음성 알림을 원하는 이벤트 카테고리, 오버레이 테마 등을 선택.
3. 설치 프로그램이 AI 코딩 어시스턴트에 적절한 훅 스크립트를 등록(예: ~/.claude/settings.json에 항목 추가).
4. 코드를 작성하는 동안 어시스턴트는 자동으로 사운드/오버레이를 트리거: 생성이 완료되면 "Work complete."가, 권한이 필요하면 "Hmm?"이 등이 출력.
5. peon toggle 또는 Claude Code 내의 슬래시 명령어 /peon-ping-toggle를 사용해 즉시 음소거/음소거 해제, 또는 macOS Focus 모드를 존중하도록 설정 가능.

왜 사용할까 – 코딩 어시스턴트를 백그라운드에서 오랫동안 실행하는 경우, 완료되었거나 제한에 도달했을 때를 놓치기 쉽습니다. peon‑ping은 음성과 시각적 신호를 제공하여 IDE를 자주 확인하지 않아도 작업 흐름을 유지할 수 있게 해줍니다.

---

설치 단축키

• Homebrew (macOS/Linux): brew install PeonPing/tap/peon-ping && peon-ping-setup
• 1라인 스크립트 (macOS/Linux/WSL2): curl … | bash
• Windows PowerShell 설치기: -All, -Packs, -Local 등 옵션 제공.
• Nix: nix run github:PeonPing/peon-ping -- status

추가 정보 – 실시간 데모는 https://peonping.com/ 에서 확인 가능. CESP 사양 리포지토리(github.com/PeonPing/openpeon), 커뮤니티 팩 레지스트리(openpeon.com)도 참조하세요.