pi-peon-adapter

A small pi extension that forwards selected pi lifecycle events to the peon executable from the PeonPing project.

PeonPing can then play sounds for events such as submitted prompts, failed bash commands, and completed agent turns.

When and why to use this extension

This is not the first attempt to write a PeonPing variant for pi. A few already exist, and some are well-crafted. However, they come with trade-offs:

• some essentially reimplement PeonPing inside pi, including sound handling, lifecycle behavior, and terminal interaction
• some target older pi APIs
• not all are structured for testability

Use this extension when:

• you want audio feedback on agentic events such as a completed task
• you want to use the official peon executable together with pi
• you care about well-tested code

Installation

First, make sure you have PeonPing installed. Install and configure it to your liking!

# NPM
pi install npm:pi-peon-adapter
# GitHub
pi install git:github.com/enolive/pi-peon-adapter

Install locally

Check out the code from the official code repository https://github.com/enolive/pi-peon-adapter, and then:

pi install ./pi-peon-adapter

To run once without installing:

pi -e ./pi-peon-adapter

Configuration

The extension looks for the peon executable on your PATH. You can override this by setting up the PEON_BIN environment variable to your liking.

📌 NOTE
If the executable is not found, this extension will display a startup warning and won’t activate.

export PEON_BIN=/path/to/your/peon

Set PI_PEON_ADAPTER_DEBUG_LOG to enable debug logging. This is useful when analyzing or reporting a bug. When debug logging is not configured, the adapter stays silent except for startup warnings such as a missing peon executable.

# will produce a simple log in the given path
export PI_PEON_ADAPTER_DEBUG_LOG=/tmp/pi-peon-debug.log
pi

# follow the log in a second terminal
tail -f /tmp/pi-peon-debug.log

Event mapping

| | | | | | | --- | --- | --- | :-: | --- | | pi event | PeonPing hook event | CESP category | Sound | notes | | session_start | SessionStart | session.start | 🔔 | Skips reload, fork, and contexts without UI. Uses source=resume for resume, otherwise source=startup. | | input | UserPromptSubmit | task.acknowledge or user.spam | 🔔 | Fires when user input is received. Only for contexts with UI. | | agent_settled | Stop | task.complete | 🔔 | Sent once after an agent run has fully settled (no pending retry, compaction, or continuation), so the sound fires exactly once per task. | | tool_execution_end | PostToolUseFailure | task.error | 🔔 | Only for failed bash executions: isError=true and toolName=bash. Scoping to bash is deliberate: PeonPing reserves task.error for command failures, not tool errors in general. | | session_before_compact | PreCompact | resource.limit | 🔔 | Sent before compaction starts. | | session_shutdown | SessionEnd | session.end | 🔇 | Sent when the session runtime is shutting down. Cleanup only, PeonPing plays no sounds. | | (not applicable) | PermissionRequest | input.required | 🔇 | pi does not support this event, so peon never receives it. |

Every payload includes cwd and a session_id prefixed with pi-.

💡 TIP
You can turn individual CESP categories on and off to your likings in PeonPing’s Configuration.

Commands

This extension intentionally does not implement any pi commands such as /peon-disable or /peon-enable. You can always run the executable directly from the pi prompt and use all available commands.

From pi, use a user shell command:

# turns peon on and off
!!peon toggle

Separate PeonPing sound pack from the author

💡 TIP
This adapter does not bundle or require any sound pack. However, I also created a separate sound pack for PeonPing with the voice of 2B from Nier Automata. Check it out, especially if you get tired of the default voice pack!

Inspiration

• PeonPing adapter for OpenCode on GitHub
• helle253@pi-peon on GitHub