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