pi-toast

A pi extension that sends desktop toast notifications when the agent finishes a turn.

Usage

Once installed and configured, pi-toast fires a notification on the agent_end event. The notification includes:

• Title — Agent finished with a session label. When running inside tmux, the label includes the tmux session name (e.g. Agent finished (mysession)). Outside tmux, the label is (shell).
• Message — A 200-character preview of the last assistant message.

Configuration

Configuration is loaded from two JSON files (project overrides global, global overrides defaults):

Location	Purpose
~/.pi/agent/pi-toast.json	Global config (applies to all projects)
<project>/.pi/pi-toast.json	Project-level config (overrides global)

Options

{
  // Path to a notification executable. The executable must accept two
  // positional arguments: <title> <message>.
  // When unset, notifications are disabled.
  "path": "/usr/bin/notify-send"
}

The only key is path. If omitted, the extension logs a warning and does nothing.

Example: notify-send (Linux)

{ "path": "/usr/bin/notify-send" }

Example: terminal-notifier (macOS)

{ "path": "/usr/local/bin/terminal-notifier" }

Any executable that accepts <title> <message> as positional arguments will work.

Development

# Run tests from the workspace root
cd ../.. && pnpm run test

# Test locally with pi (from this package directory)
pi -e ./index.ts