pi-toast

Desktop toast notifications for the Pi coding agent via dunst-recv and dunst.

Sends a toast when the agent finishes a task, asks a question, or when the LLM calls the notify tool. Shows human-readable session names derived from your first message.

Install

pi install npm:pi-toast

Or from a local checkout:

pi install /path/to/pi-toast

Requires dunst-recv on PATH:

pip install dunst-recv

Usage

Agent task complete

When pi finishes responding, a toast shows the session name as title and a brief summary as body:

┌─────────────────────────────────┐
│ Fix the Docker Networking Config│
│ Network reconfigured for labnet │
└─────────────────────────────────┘

User question needed

When pi calls ask_user_question, a critical sticky toast is sent:

┌─────────────────────────────────┐
│ Refactor Auth Module            │
│ Which library should we use?    │
└─────────────────────────────────┘

LLM-driven notifications

The LLM can call the notify tool to proactively alert:

pi > Send me a toast when the build is done
# Agent runs build, then calls notify("Build", "Tests passed", "normal")

Slash commands

| Command | Description | |---------|-------------| | /notify on | Enable toasts (default) | | /notify off | Disable toasts (persists per-cwd) | | /notify | Show current status |

Session naming

Pi-toast derives human-readable session names from your first message by stripping filler phrases and applying title case:

| You type | Session name | |----------|-------------| | "I need you to fix the Docker networking config" | Fix the Docker Networking Config | | "please create a backup script for the database" | Create a Backup Script for the Database | | "add auth middleware to the API" | Add Auth Middleware to the API |

Disambiguators are appended when a name already exists: "Fix Bug (2)".

Notify tool

The LLM has access to a notify tool with these parameters:

| Parameter | Type | Description | |-----------|------|-------------| | title | string | Short title (≤ 50 chars) | | message | string | Brief message (≤ 60 chars) | | priority | low / normal / critical | Default: normal |

Titles and messages are automatically truncated to fit the toast area.

File layout

pi-toast/
├── extensions/
│   └── toast.ts      # Pi extension: session naming + notifications
├── package.json
├── tsconfig.json
└── README.md

License

MIT