pi-notify-koko

pi-notify-koko triggers Koko voice playback when the Pi agent completes a turn.

• Pi agent: https://github.com/badlogic/pi-mono
• Koko CLI: https://github.com/rbright/koko
• npm package: @rbright/pi-notify-koko

Install into Pi (npm, recommended)

Global install:

pi install npm:@rbright/pi-notify-koko

Project-local install:

pi install -l npm:@rbright/pi-notify-koko

Git install fallback:

pi install git:github.com/rbright/pi-notify-koko
pi install -l git:github.com/rbright/pi-notify-koko

If Pi is already running, reload extensions:

/reload

How it works

The extension is zero-config by default.

• completion trigger: final assistant message_end (non-tool) with agent_end fallback
• per-agent dedupe: one Koko invocation per completed agent run
• speaks the last assistant response text (sanitized, no truncation)
• strips markdown/link formatting, wrapper symbols, and emojis before speaking
• if no assistant response text is available, it says nothing
• skips non-TTY sessions by default

Configuration (optional)

| Variable | Default | Description | | --- | --- | --- | | PI_NOTIFY_KOKO_ENABLED | true | Enable/disable notifications | | PI_NOTIFY_KOKO_COMMAND | koko | Koko executable name/path | | PI_NOTIFY_KOKO_TIMEOUT_MS | 15000 | Subprocess timeout in ms | | PI_NOTIFY_KOKO_ALLOW_NON_TTY | false | Allow triggering in non-TTY contexts | | PI_NOTIFY_KOKO_VOICE | unset | Passed as --voice <value> | | PI_NOTIFY_KOKO_MODEL_DIR | unset | Passed as --model-dir <value> | | PI_NOTIFY_KOKO_NO_PLAY | false | Adds --no-play | | PI_NOTIFY_KOKO_ARGS_JSON | unset | JSON array of extra args (e.g. ["--device","cpu"]) |

Example:

export PI_NOTIFY_KOKO_VOICE=af_heart
pi

Troubleshooting

1. Confirm extension install: pi list
2. If Pi was open during install/update, run /reload
3. Confirm Koko is on PATH: command -v koko
4. Run a short prompt and wait for completion
5. If no sound but command works, test Koko directly (for example: koko "test")

Development

just deps
just lint
just typecheck
just test
just check
just precommit-install
just precommit-run

Run extension directly during local development:

bun install
pi --no-extensions -e ./src/index.ts

Publishing

Manual publish (@rbright/pi-notify-koko):

bun run check
npm publish --access public

Automated publish via GitHub Actions (.github/workflows/publish.yml) runs on:

• workflow_dispatch
• tag pushes matching v*

Required repository secret:

• NPM_TOKEN (npm token with publish permission)