# pi-toast

Desktop toast notifications for the [Pi coding agent](https://pi.dev) via
[dunst-recv](https://github.com/greedy/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

```bash
pi install npm:pi-toast
```

Or from a local checkout:

```bash
pi install /path/to/pi-toast
```

Requires `dunst-recv` on PATH:

```bash
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