PeonPing

Product Introduction

1. Definition: PeonPing is a developer productivity tool (technical category: AI agent notification system) that triggers game-character audio alerts for coding events. It integrates directly with AI development agents like Claude Code, Cursor, and Codex via CLI hooks or its MCP (Message Control Protocol) server.
2. Core Value Proposition: It eliminates workflow disruption caused by silent terminals by providing instant, recognizable sound notifications for AI agent status changes (task completion, errors, permission requests), reducing context-switching for developers.

Main Features

1. AI Agent Sound Hooks:

   • How it works: Monitors CLI output of supported AI agents (Claude Code, Cursor, Codex, etc.) via regex pattern matching. Triggers categorized sounds (greeting/acknowledge/error) when detecting task completion, errors, or permission prompts.
   • Technology: Uses WebSocket connections for real-time terminal monitoring and system audio APIs for cross-platform playback (macOS/Linux/WSL2).

2. MCP Server Integration:

   • How it works: Launches a local MCP server (HTTP/TCP) allowing AI agents to autonomously request specific sounds via API calls (e.g., play_sound("permission") from Claude Code scripts).
   • Technology: Node.js-based server with REST endpoints for dynamic sound selection by the AI agent itself.

3. Sound Pack Ecosystem:

   • How it works: 100+ curated sound packs (Warcraft, StarCraft, Portal’s GLaDOS, TF2) installable via CLI (peon packs install). Each pack categorizes sounds by event type (error/annoyed/complete) with language variants.
   • Technology: Decentralized registry (openpeon.com) hosting GitHub-hosted packs; YAML configuration for pack management.

4. Peon Trainer Mode:

   • How it works: Forces developer breaks with exercise reminders (pushups/squats) triggered at session start, periodic intervals (~20 mins), and goal completion (300 reps). Logs reps via CLI command /peon-ping-log.
   • Technology: Background scheduler with escalation logic for ignored reminders; integrates with Claude Code sessions.

5. Desktop Companion & Notifications:

   • How it works: Electron-based animated "Peon Pet" (orc Tamagotchi) reacts to coding events in real-time. Augments sounds with desktop notifications (OS-native) when terminals are unfocused.
   • Technology: Three.js for animations; libnotify for Linux/macOS alerts.

Problems Solved

1. Pain Point: Silent terminal workflows causing missed AI agent status updates (completion/errors), forcing manual monitoring and productivity loss.
2. Target Audience:
   • AI-assisted developers using Claude Code/Cursor/Codex
   • Remote engineers managing multiple terminals
   • Gaming enthusiasts seeking workflow personalization
3. Use Cases:
   • Audible alert when Claude finishes debugging while developer is in Slack
   • Permission request sounds during code reviews
   • Visual terminal tab status indicators during multi-project work

Unique Advantages

1. Differentiation: Unlike generic notification tools (e.g., terminal-notifier), PeonPing offers agent-triggered sounds via MCP, contextual event categorization, and gaming-grade audio customization.
2. Key Innovation: MCP protocol enabling AI agents to self-select sounds – a first in developer tools – and open sound pack registry for community expansions.

Frequently Asked Questions (FAQ)

1. Does PeonPing support Windows development environments?
   PeonPing currently supports macOS, Linux, and WSL2. Native Windows support is planned for Q4 2024.

2. How to add custom sound packs to PeonPing?
   Create a GitHub repo with categorized audio files (greeting/error/annoyed), register it at openpeon.com, then install via peon packs install <repo-url>.

3. Can PeonPing mute notifications during meetings?
   Yes, configure category toggles (greeting/acknowledge/error) or global volume (0.0–1.0) in ~/.peon/config.yaml.

4. What IDEs does PeonPing integrate with besides Claude Code?
   Supports Cursor, Codex, OpenCode, Kiro, Antigravity, and any IDE with CLI output hooks or MCP client capabilities.

5. Is the MCP server secure for local development?
   The MCP server runs locally (127.0.0.1), requires no internet access, and uses token-based authentication for agent requests.