@xynogen/pix-notify

Pi extension — sound + popup when the agent waits on you (herdr-aware, OS-agnostic)

Package details

extension

Install @xynogen/pix-notify from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:@xynogen/pix-notify

Pi manifest JSON

{
  "extensions": [
    "src/index.ts"
  ]
}

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

Sound (and popup in herdr) when the agent waits on you: ask_user, a pix-gate approval, sudo_run/ssh_run/Python/env approval.

It listens to pix:agent-state from @xynogen/pix-runtime and fires once per entry into blocked, never repeatedly.

Where	What happens
herdr pane + herdr's Pi integration (`herdr integration install pi`)	emits `herdr:blocked {active, label}` on enter/leave; herdr shows `blocked` in the sidebar and plays its own toast + sound (`[ui.toast]`, `[ui.sound]` in herdr's `config.toml`)
herdr pane, no integration	`herdr notification show <message> --sound request`
elsewhere, or herdr missing	plays a system sound with the OS's own player

The integration is detected by its file, <agentDir>/extensions/herdr-agent-state.ts.

The OS ships both the sounds and the player:

OS	Sounds	Player
Linux	`$XDG_DATA_DIRS/sounds/freedesktop/stereo`	`paplay` (or `pw-play`)
macOS	`/System/Library/Sounds`	`afplay`
Windows	`%SystemRoot%\Media`	PowerShell `Media.SoundPlayer`

No sound or player found → silent.

Stored in the notify section of ~/.pi/agent/pix.json:

Key	Default	Meaning
`enabled`	`true`	Play a sound when the agent waits on you
`sound`	`"auto"`	`auto` (OS default), an installed system sound name, or a file path

The tab also has a test row. In a herdr pane with the integration, herdr owns the sound; change it in herdr's config.toml.

Bundled in @xynogen/pix-core.