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.
agent_end	Stop	task.complete	🔔	Sent when an agent turn ends.
tool_execution_end	PostToolUseFailure	task.error	🔔	Only for failed bash executions: isError=true and toolName=bash.
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