peon (PeonPing/peon-ping)

peon (PeonPing/peon-ping) | MoltPulse

brew install PeonPing/tap/peon-ping

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

On Windows 10 / Windows 11 pre-24H2, WPF MediaPlayer is used directly — native MP3 + WAV, no extra dependencies.
On Windows 11 24H2+ (build 26100+), Microsoft removed legacy Windows Media Player from the OS and WPF MediaPlayer fails (MILAVERR_INVALIDWMPVERSION). peon-ping falls back to System.Media.SoundPlayer, which uses the Win32 PlaySound API and works everywhere — but it's WAV-only, so MP3 packs require ffmpeg to transcode on the fly:
```
sudo apt update; sudo apt install -y ffmpeg
```

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.ps1" -OutFile ".\install.ps1" -UseBasicParsing
powershell -ExecutionPolicy Bypass -File .\install.ps1

powershell -ExecutionPolicy Bypass -File .\install.ps1 -All
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Packs peon,sc_kerrigan
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Local
powershell -ExecutionPolicy Bypass -File .\install.ps1 -InitLocalConfig

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12

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

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

nix develop  # or use direnv

# In your home.nix or flake.nix
{ inputs, pkgs, ... }:

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

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

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

    # Install packs from og-packs (simple string notation)
    # and custom sources (attrset with name + src)
    installPacks = [
      "peon"
      "glados"
      "sc_kerrigan"
      # Custom pack from GitHub (openpeon.com registry)
      {
        name = "mr_meeseeks";
        src = pkgs.fetchFromGitHub {
          owner = "kasperhendriks";
          repo = "openpeon-mrmeeseeks";
          rev = "main";  # or use a commit hash for reproducibility
          sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
        };
      }
    ];
    enableZshIntegration = true;
  };

  # Optional extra IDE hooks, like Cursor
  home.file.".cursor/hooks.json".text = builtins.toJSON {
    version = 1;
    hooks = {
      afterAgentResponse = [{ command = "bash ${peonCursorAdapterPath} afterAgentResponse"; }];
      stop               = [{ command = "bash ${peonCursorAdapterPath} stop"; }];
    };
  };
}

{
  name = "pack_name";
  src = pkgs.fetchFromGitHub {
    owner = "github-owner";
    repo = "repo-name";
    rev = "main";  # or a commit hash/tag
    sha256 = "";   # Leave empty first, Nix will tell you the correct hash
  };
}

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

peon setup                # Interactive setup wizard (volume, categories, notifications)
peon pause                # Mute sounds
peon resume               # Unmute sounds
peon mute                 # Alias for 'pause'
peon unmute               # Alias for 'resume'
peon status               # Check if paused or active (concise)
peon status --verbose     # Show full details (notifications, headphones, IDEs, etc.)
peon volume               # Show current volume
peon volume 0.7           # Set volume (0.0–1.0)
peon rotation             # Show current rotation mode
peon rotation random      # Set rotation mode (random|round-robin|session_override)
peon packs list           # List installed sound packs
peon packs list --registry # Browse all available packs in the registry
peon packs community      # List all registry packs grouped by trust tier (Windows)
peon packs search <query> # Search registry packs by name (Windows)
peon packs install <p1,p2> # Install packs from the registry
peon packs install --all  # Install all packs from the registry
peon packs install-local <path> # Install a pack from a local directory
peon packs use <name>     # Switch to a specific pack (auto-installs from registry on Windows)
peon packs use --install <name>  # Switch to pack, installing from registry if needed
peon packs next           # Cycle to the next pack
peon packs remove <p1,p2> # Remove specific packs
peon packs bind <name>    # Bind a pack to the current directory
peon packs bind --pattern <path> # Bind a pack to a directory pattern, e.g. "*/services"
peon packs unbind         # Remove the current directory
peon packs bindings       # List all assigned bindings
peon packs ide-bind <ide> <name> # Bind a pack to an IDE id, e.g. codex
peon packs ide-unbind <ide> # Remove an IDE binding
peon packs ide-bindings   # List all IDE-based bindings
peon packs exclude add <path> # Silence sounds & notifications for a glob or directory
peon packs exclude remove <path> # Stop silencing the given path
peon packs exclude list   # List silenced paths
peon sounds list [pack]   # List sounds in a pack, marking disabled ones
peon sounds disable <category> <file> [--pack=<name>]  # Mute a single sound within a pack
peon sounds enable <category> <file> [--pack=<name>]   # Re-enable a previously disabled sound
peon notifications on     # Enable desktop notifications
peon notifications off    # Disable desktop notifications
peon notifications overlay   # Use large overlay banners (default)
peon notifications standard  # Use standard system notifications
peon notifications test      # Send a test notification
peon notifications position [pos]    # Get/set notification position (top-left, top-center, top-right, bottom-left, bottom-center, bottom-right)
peon notifications dismiss [N]       # Get/set auto-dismiss time in seconds (0 = persistent)
peon notifications label [text|reset] # Get/set project label override for notifications
peon notifications template [key] [fmt]  # Get/set/reset message templates (keys: stop, permission, error, idle, question)
peon preview              # Play all sounds from session.start
peon preview <category>   # Play all sounds from a specific category
peon preview --list       # List all categories in the active pack
peon mobile ntfy <topic>  # Set up phone notifications (free)
peon mobile off           # Disable phone notifications
peon mobile test          # Send a test notification
peon debug on             # Enable debug logging
peon debug off            # Disable debug logging
peon debug status         # Show debug state, log directory, file count, total size
peon logs                 # Show last 50 lines of today's log
peon logs --last N        # Show last N lines across all log files
peon logs --session ID    # Filter today's log by session ID
peon logs --session ID --all  # Search all log files for session ID
peon logs --clear         # Delete all log files (with confirmation)
peon relay --daemon       # Start audio relay (for SSH/devcontainer)
peon relay --stop         # Stop background relay

peon setup

  ╔══════════════════════════════════════╗
  ║       peon-ping  setup wizard        ║
  ╚══════════════════════════════════════╝

  ── Volume ──
  > Volume (0.0 - 1.0) (0.5):

  ── Sound categories ──
  >   Session start [on/off] (on):
  >   Task acknowledge [on/off] (off):
  >   Task complete [on/off] (on):
  >   Task error [on/off] (on):
  >   Input required (permissions, questions) [on/off] (on):
  >   Resource limit (context compaction) [on/off] (on):
  >   User spam (rapid prompts) [on/off] (on):

  ── Notifications ──
  > Desktop notifications [on/off] (on):

  Overlay theme:
    1) Neon (cyberpunk)
    2) Glass (translucent)
    3) Sakura (cherry blossom)
    4) Jarvis (iron man)
  > Theme [neon]:

  Notification position:
    1) Top center
    2) Top right
    ...
  > Position [top-center]:

  Auto-dismiss:
    1) Persistent (click to dismiss)
    2) 3 seconds
    3) 4 seconds
    ...
  > Dismiss time [4]:

  ✓ Configuration saved!

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

Keep sounds but disable desktop popups: peon notifications off
Keep desktop popups but disable sounds: peon pause
Enable mobile push without desktop popups: set desktop_notifications: false and mobile_notify.enabled: true
volume: 0.0–1.0 (quiet enough for the office)
desktop_notifications: true/false — toggle desktop notification popups independently from sounds (default: true). When disabled, sounds continue playing but visual popups are suppressed. Mobile notifications are unaffected.
notification_style: "overlay" or "standard" — controls how desktop notifications appear (default: "overlay")
- overlay: large, visible banners — JXA Cocoa overlay on macOS, Windows Forms popup on WSL/MSYS2. Clicking the overlay focuses your terminal (supports Ghostty, Warp, iTerm2, Zed, Terminal.app). On iTerm2, clicking focuses the correct tab/pane/window — not just the app.
- standard: system notifications — terminal-notifier / osascript on macOS, Windows toast on WSL/MSYS2. 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.
overlay_theme: "jarvis", "glass", "sakura", or omit for the default overlay — macOS only (default: none)
- jarvis: circular HUD with rotating arcs, graduation ticks, and progress ring
- glass: glassmorphism panel with accent color bar, progress line, and timestamp
- sakura: zen garden with bonsai tree and animated cherry blossom petals
categories: Toggle individual CESP sound categories on/off (e.g. "session.start": false to disable greeting sounds)
annoyed_threshold / annoyed_window_seconds: How many prompts in N seconds triggers the user.spam easter egg
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)
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.
suppress_idle_prompt_repeats (boolean, default: true): Claude Code re-fires its idle_prompt notification every ~60s while the terminal is unfocused. peon-ping routes idle_prompt to task.complete so you still get a sound when input is needed — but without dedupe the same sound replays on every poke. When true, an idle_prompt is suppressed if a task.complete for the same session already fired inside idle_prompt_suppress_window_seconds. Set to false to restore the periodic nudge.
idle_prompt_suppress_window_seconds (number, default: 3600): Window used by suppress_idle_prompt_repeats. After a task.complete fires for a session, subsequent idle_prompt notifications for that session stay silent for this many seconds. Set to 0 to disable the window (effectively the same as suppress_idle_prompt_repeats: false).
suppress_subagent_complete (boolean, default: false): Suppress sounds and notifications from sub-agent activity. When Claude Code's Task tool dispatches parallel sub-agents, each one fires its own events: a completion sound on finish, task.error on failed Bash commands, input.required on permission requests. Set this to true to hear only the parent session's sounds. Events fired from inside a sub-agent are detected via the agent_id field Claude Code adds to their hook payloads; separate-session sub-agents (older clients, other IDEs) are still detected by the SubagentStart timing heuristic.
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.
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.
```
"path_rules": [
  { "pattern": "*/work/client-a/*", "pack": "glados" },
  { "pattern": "*/personal/*",      "pack": "peon" }
]
```
exclude_dirs: Array of glob or directory patterns. If the current working directory matches one of these entries, all sounds and notifications are silenced for that invocation (the hook logs suppressed=True reason=excluded_dir pattern=<match>). Bare directory paths also match descendants, so "~/conductor/workspaces" silences everything under that tree. Use this for noisy background agents (e.g. CodexBar/ClaudeProbe), throwaway scratch dirs, or sensitive workspaces where audio alerts are unwanted.
```
"exclude_dirs": [
  "~/conductor/workspaces",
  "~/Library/Application Support/CodexBar*"
]
```
ide_rules: Array of { "ide": "...", "pack": "..." } objects. Assigns a pack by IDE/source after path_rules and before rotation/default fallback. First matching rule wins. Common ids: claude, codex, cursor, opencode, kilo, kiro, gemini, copilot, windsurf, kimi, antigravity, amp, deepagents, openclaw, rovodev.
```
"ide_rules": [
  { "ide": "codex",  "pack": "glados" },
  { "ide": "claude", "pack": "peon" }
]
```
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 / ide_rules) only.
pack_rotation_mode: "random" (default), "round-robin", or "session_override". With random/round-robin, each session picks one pack from pack_rotation. With session_override, the /peon-ping-use <pack> 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".)
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.
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).
terminal_tab_title (boolean, default: true): Update the terminal tab title with the current session status (for example ● project: done). Set to false if you already manage tab titles with your own shell prompt or terminal automation and only want peon-ping's sounds/notifications.
tmux_passthrough (boolean, default: false): Pass the tab title and iTerm2 tab-color escapes through tmux's DCS passthrough to the host terminal (requires tmux 3.3a+ with set -g allow-passthrough on). Off by default because a tmux client multiplexes many panes/windows onto a single host terminal tab with no per-pane addressing: when several agent sessions run at once, every hook (including from background panes) repaints that one shared tab on a last-writer-wins basis, so it no longer reflects any single session. Leave it off and let tmux's own window/status line carry per-session state; enable it only if you run one tmux window per terminal tab (so 1 tab = 1 session). Has no effect outside tmux, where the escapes are always emitted.
suppress_sound_when_tab_focused (boolean, default: false): Skip sound playback when the terminal tab that generated the hook event is the currently active/focused 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).
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.
focus_detect (boolean, default: false): Honor macOS Focus / Do Not Disturb. peon-ping plays sounds via afplay and draws overlays in a custom window, and both bypass Notification Center, so the system Focus toggle has no effect on them by default. When enabled, peon-ping reads the Focus state directly and suppresses output whenever any Focus (Do Not Disturb, Work, Sleep, etc.) is active, then resumes automatically when you turn Focus off. Mobile push (if configured) is unaffected, since your phone honors its own Focus. macOS only, and it fails open (if the Focus state can't be read, sounds play as normal).
focus_detect_mode (string, default: "all"): What focus_detect suppresses while a Focus is active. "all" mutes both the sound and the overlay/desktop notification. "sound" mutes only the sound (notifications still appear). "notifications" mutes only the notification (sound still plays). Ignored when focus_detect is false.
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".
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.
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.
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.
notification_title_override (string, default: ""): Override the project name shown in notification titles. When empty, the project name is auto-detected from /peon-ping-rename > CLAUDE_SESSION_NAME > .peon-label > notification_title_script > project_name_map > git repo name > folder name.
notification_title_marker (string, default: "●"): Character(s) shown before the project name in notification titles and terminal tab titles. Desktop notification titles use Project by default; terminal tab titles keep Project: status. Set to "" to disable. Example: "🔔".
notification_title_ide (boolean, default: false): Include the normalized IDE label in desktop notification titles as Project - IDE. When disabled, the title stays Project and the message/body carries the status/details.
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_IDE, PEON_SESSION_NAME. Use stdout (trimmed, max 50 chars); non-zero exit falls through to the next tier. PEON_IDE is the normalized IDE/source id such as codex or claude. Example: "basename $PEON_CWD".
project_name_map (object, default: {}): Map directory paths to custom project labels for notifications. Keys are path patterns, values are display names. Example: { "/home/user/work/client-a": "Client A" }.
notification_templates (object, default: {}): Custom message/body format strings for notification events. Keys are event types (stop, permission, error, idle, question), values are template strings with variable substitution. Available variables: {project}, {ide}, {ide_id}, {summary}, {tool_name}, {status}, {event}. Example: { "stop": "{status}: {summary}", "permission": "{status}: {tool_name}" }.

peon packs bind glados                     # Bind glados to the current directory
peon packs bind sc_kerrigan --pattern "*/services/*"  # Bind to a glob pattern
peon packs bind duke_nukem --install       # Bind and install from registry if needed
peon packs unbind                          # Remove binding for the current directory
peon packs unbind --pattern "*/services/*" # Remove a specific pattern binding
peon packs bindings                        # List all bindings

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

peon packs ide-bind codex glados        # Use glados for Codex sessions
peon packs ide-bind claude peon         # Use peon for Claude Code
peon packs ide-unbind codex             # Remove one IDE rule
peon packs ide-bindings                 # List IDE rules and recent detections

"ide_rules": [
  { "ide": "codex",  "pack": "glados" },
  { "ide": "claude", "pack": "peon" }
]

peon notifications off

peon popups off

peon pause  # or set "enabled": false in config

peon pause
peon notifications off
peon mobile off

peon trainer on              # enable trainer
peon trainer goal 200        # set daily goal (default: 300/300)
# ... code for a while, peon nags you every ~20 min ...
peon trainer log 25 pushups  # log what you did
peon trainer log 30 squats
peon trainer status          # check progress

peon trainer goal pushups 300         # 300 pushups every day (uniform)
peon trainer goal pushups mon 400     # Override: 400 on Monday (creates schedule)
peon trainer goal squats sun 0        # Rest day for squats on Sunday
peon trainer goal fri 150             # Light day for all exercises on Friday

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

trainer/sounds/session_start/  # session greeting ("Pushups first, code second! Zug zug!")
trainer/sounds/remind/         # reminder lines ("Something need doing? YES. PUSHUPS.")
trainer/sounds/log/            # acknowledgment ("Work work! Muscles getting bigger maybe!")
trainer/sounds/complete/       # celebration ("Zug zug! Human finish all reps!")
trainer/sounds/slacking/       # disappointment ("Peon very disappointed.")

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

| IDE | Status | Setup | |---|---|---| | Claude Code | Built-in | curl \| bash install handles everything | | Amp | Adapter | bash adapters/amp.sh / powershell adapters/amp.ps1 (setup) | | Gemini CLI | Adapter | Add hooks pointing to adapters/gemini.sh (or .ps1 on Windows) (setup) | | GitHub Copilot CLI | Built-in (auto-detect) | install.sh / install.ps1 auto-registers hooks at ~/.copilot/hooks/peon-ping.json if ~/.copilot exists. Per-repo manual wiring also available via adapters/copilot.sh / .ps1 (setup) | | OpenAI Codex | Built-in (auto-detect) | install.sh / install.ps1 auto-registers stable hooks in ~/.codex/config.toml if ~/.codex exists. The adapter is also available for manual wiring (setup) | | 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 ~/.claude/settings.json for SessionStart/Stop sounds. | | OpenCode | Adapter | bash adapters/opencode.sh / powershell adapters/opencode.ps1 (setup) | | Kilo CLI | Adapter | bash adapters/kilo.sh / powershell adapters/kilo.ps1 (setup) | | Kiro | Adapter | Add hook entries pointing to adapters/kiro.sh (or .ps1) (setup) | | Windsurf | Adapter | Add hook entries pointing to adapters/windsurf.sh (or .ps1) (setup) | | Google Antigravity | Adapter | bash adapters/antigravity.sh / powershell adapters/antigravity.ps1. For headless / macOS LaunchAgent use, also see bash adapters/antigravity-py.sh --install (Python watchdog watcher with 25s idle threshold; requires pip3 install watchdog). The Python watcher supports legacy conversations/*.pb state plus newer antigravity-cli / antigravity-ide conversations/*.db and brain/**/transcript*.jsonl layouts. | | Kimi Code | Adapter | bash adapters/kimi.sh --install / powershell adapters/kimi.ps1 -Install (setup) | | OpenClaw | Adapter | Call adapters/openclaw.sh <event> (or openclaw.ps1) from your OpenClaw skill | | Rovo Dev CLI | Adapter | Auto-registered by install.sh if ~/.rovodev exists, or add hooks to ~/.rovodev/config.yml manually (setup) | | DeepAgents | Adapter | bash adapters/deepagents.sh / powershell adapters/deepagents.ps1 (setup) | | oh-my-pi (omp) | Adapter | bash adapters/omp.sh (setup) | | Qwen Code | Adapter | Add hooks pointing to adapters/qwen.sh (or .ps1 on Windows) (setup) | | iFlow CLI | Adapter | Add hooks pointing to adapters/iflow.sh (or .ps1) (setup) | | Trae | Adapter | Filesystem watcher: bash adapters/trae.sh & / powershell adapters/trae.ps1 -Install (setup) | | Kiro IDE | Adapter | Agent hooks in .kiro/hooks/*.kiro.hook calling adapters/kiro-ide.sh (or .ps1) (setup) | | ECA | Adapter | Add a shell hook pointing to adapters/eca.sh (or .ps1) (setup) |

Install the peon-ping runtime:

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

Or with the standard installer:

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

Open Codex and run /hooks if prompted. Codex requires non-managed command hooks to be reviewed and trusted before they run.
Restart Codex if it was already running during installation.

Ensure peon-ping is installed (curl -fsSL https://peonping.com/install | bash)

Install fswatch (macOS) or inotify-tools (Linux):

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

Start the watcher:

bash ~/.claude/hooks/peon-ping/adapters/amp.sh        # foreground
bash ~/.claude/hooks/peon-ping/adapters/amp.sh &       # background

winget install Microsoft.PowerShell
powershell -NoProfile -Command "Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force"

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh sessionStart",
        "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 sessionStart"
      }
    ],
    "agentStop": [
      {
        "type": "command",
        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh agentStop",
        "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 agentStop"
      }
    ],
    "postToolUseFailure": [
      {
        "type": "command",
        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh postToolUseFailure",
        "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 postToolUseFailure"
      }
    ],
    "notification": [
      {
        "type": "command",
        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh notification",
        "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 notification"
      }
    ]
  }
}

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

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

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

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

Ensure peon-ping is installed (curl -fsSL https://peonping.com/install | bash)

Add the following hooks to your ~/.gemini/settings.json:

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

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

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

Ensure peon-ping is installed (curl -fsSL https://peonping.com/install | bash)

Add to ~/.rovodev/config.yml:

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

Restart Rovo Dev CLI for the hooks to take effect.

# Install (starts background daemon)
bash ~/.claude/hooks/peon-ping/adapters/kimi.sh --install

# Check status / stop
bash ~/.claude/hooks/peon-ping/adapters/kimi.sh --status
bash ~/.claude/hooks/peon-ping/adapters/kimi.sh --uninstall

curl -fsSL peonping.com/install | bash -s -- --kimi

curl -fsSL peonping.com/install | bash -s -- --openpeon
# Windows: powershell -File install.ps1 -OpenPeon

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

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

{
  "hooks": {
    "SessionStart":       [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }],
    "UserPromptSubmit":   [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }],
    "Stop":               [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }],
    "Notification":       [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }],
    "PostToolUseFailure": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }],
    "SessionEnd":         [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }]
  }
}

{
  "hooks": {
    "SessionStart":     [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }],
    "Stop":             [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }],
    "Notification":     [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }],
    "PostToolUse":      [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }],
    "SessionEnd":       [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }]
  }
}

# Foreground
bash ~/.claude/hooks/peon-ping/adapters/trae.sh
# Background
bash ~/.claude/hooks/peon-ping/adapters/trae.sh &

{
  "version": "1.0.0",
  "enabled": true,
  "name": "peon-ping-stop",
  "when": { "type": "agentStop" },
  "then": {
    "type": "runCommand",
    "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro-ide.sh agentStop"
  }
}

{
  "hooks": {
    "sessionStart": [{ "actions": [{ "type": "shell", "command": "bash ~/.claude/hooks/peon-ping/adapters/eca.sh sessionStart" }] }],
    "preRequest":   [{ "actions": [{ "type": "shell", "command": "bash ~/.claude/hooks/peon-ping/adapters/eca.sh preRequest" }] }],
    "postRequest":  [{ "actions": [{ "type": "shell", "command": "bash ~/.claude/hooks/peon-ping/adapters/eca.sh postRequest" }] }],
    "preToolCall":  [{ "actions": [{ "type": "shell", "command": "bash ~/.claude/hooks/peon-ping/adapters/eca.sh preToolCall" }] }],
    "sessionEnd":   [{ "actions": [{ "type": "shell", "command": "bash ~/.claude/hooks/peon-ping/adapters/eca.sh sessionEnd" }] }]
  }
}

On your local machine, start the relay:
```
peon relay --daemon
```

SSH with port forwarding:

ssh -R 19998:localhost:19998 your-server

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.

peon ssh-audio relay   # default, always use relay
peon ssh-audio auto    # try relay, fall back to local playback on SSH host
peon ssh-audio local   # always play on SSH host

peon relay                # Start relay in foreground
peon relay --daemon       # Start in background
peon relay --stop         # Stop background relay
peon relay --status       # Check if relay is running
peon relay --port=12345   # Custom port (default: 19998)
peon relay --bind=0.0.0.0 # Listen on all interfaces (less secure)

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

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

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

peon mobile ntfy my-peon-notifications --priority=max

"mobile_notify": {
  "service": "ntfy",
  "topic": "my-peon-notifications",
  "server": "https://ntfy.sh",
  "priority": "max"
}

peon mobile on            # Enable mobile notifications
peon mobile off           # Disable mobile notifications
peon mobile status        # Show current config
peon mobile test          # Send a test notification

peon packs use glados             # switch to a specific pack
peon packs use --install glados   # install (or update) and switch in one step
peon packs next                   # cycle to the next pack
peon packs list                   # list all installed packs
peon packs list --registry        # browse all available packs
peon packs install glados,murloc  # install specific packs
peon packs install --all          # install every pack in the registry

peon debug on             # Enable — logs written to ~/.claude/hooks/peon-ping/logs/
peon debug off            # Disable
peon debug status         # Show state, log directory, file count, total size

peon logs                 # Last 50 lines of today's log
peon logs --last 100      # Last 100 lines across all log files
peon logs --session <ID>  # Filter today's log by session ID
peon logs --session <ID> --all  # Search all log files for session ID
peon logs --clear         # Delete all log files (with confirmation)

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

bash "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/uninstall.sh        # global
bash .claude/hooks/peon-ping/uninstall.sh           # project-local

# Standard uninstall (prompts before deleting sounds)
powershell -File "$env:USERPROFILE\.claude\hooks\peon-ping\uninstall.ps1"

# Keep sound packs (removes everything else)
powershell -File "$env:USERPROFILE\.claude\hooks\peon-ping\uninstall.ps1" -KeepSounds

peon

MoltPulse

peon-ping

Install

Option 1: Homebrew (recommended)

Option 2: Installer script (macOS, Linux, WSL2)

Option 3: Installer for Windows

Option 4: Clone and inspect first

Option 5: Nix (macOS, Linux)

Home Manager module (declarative configuration)

What you'll hear

Quick controls

Configuration

Quickstart — peon setup

Slash commands and manual config

Independent Controls

Pack Selection Hierarchy

Per-Project Pack Assignment (path_rules)

Per-IDE Pack Assignment (ide_rules)

Common Use Cases

Sounds without popups

Silent mode with notifications only

Complete silence

Peon Trainer

Quick start

How it works

Commands

Schedule vs uniform goals

Claude Code skill

Custom voice lines

MCP server

Setup

What the agent can do

Multi-IDE Support

OpenAI Codex setup

Amp setup

GitHub Copilot CLI setup

OpenCode setup

Kilo CLI setup

Gemini CLI setup

Windsurf setup

Kiro setup

Rovo Dev CLI setup

Kimi Code setup

Tool-agnostic install root (--openpeon)

oh-my-pi (omp) setup

Qwen Code setup

iFlow CLI setup

Trae setup

Kiro IDE setup

ECA setup

Remote development (SSH / Devcontainers / Codespaces)

SSH setup

Devcontainers / Codespaces

Relay commands

Category-based API (for lightweight remote hooks)

Mobile notifications

Quick start (ntfy.sh — free, no account needed)

Notification priority (ntfy)

Mobile commands

Sound packs

Debugging

Enabling debug logs

Reading logs

Log format

Common failure examples

Config keys

Uninstall

Requirements

How it works

Links

Support the project

Ecosystem Role

Embed Badge

Quickstart — `peon setup`

Tool-agnostic install root (`--openpeon`)