# Pi Notification Extension

A small extension for [`@mariozechner/pi-coding-agent`](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) that notifies you when the agent is **idle and waiting for input**.

Supports:
- Telegram message (Bot API)
- Terminal bell + optional `bellCommand` (useful on Windows/WSL2 + Alacritty)

## Install

Copy the extension to Pi’s global extensions folder:

```bash
cp ./notification.ts ~/.pi/agent/extensions/notification.ts
```

Then restart `pi`.

## Configure

Pi settings live in:
- Global: `~/.pi/agent/settings.json`
- Project overrides: `<project>/.pi/settings.json`

This extension reads both and merges them (project overrides win).

### Minimal Telegram config

Add this to `~/.pi/agent/settings.json` (fill in your values):

```json
{
  "notifications": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABCDEF...",
      "chatId": "123456789"
    }
  }
}
```

You can also provide credentials via env vars instead of settings:
- `TELEGRAM_BOT_TOKEN` or `PI_TELEGRAM_TOKEN`
- `TELEGRAM_CHAT_ID` or `PI_TELEGRAM_CHAT_ID`

### Optional bell + Windows sound

```json
{
  "notifications": {
    "bell": true,
    "bellCommand": "powershell.exe -NoProfile -Command \"[System.Media.SystemSounds]::Asterisk.Play()\"",
    "bellCommandTimeoutMs": 1500
  }
}
```

### Telegram options

```json
{
  "notifications": {
    "telegram": {
      "enabled": true,
      "timeoutMs": 5000,
      "forceIpv4": true,
      "includePrompt": false,
      "includeToolErrors": true,
      "includeLeaf": false,
      "includeStarted": false
    }
  }
}
```

Notes:
- `forceIpv4` defaults to `true` to avoid common WSL2 IPv6 issues.
- Messages are sent using Telegram `parse_mode: "HTML"`.

## Test

In Pi, run:
- `/notify` to send a test notification
- `/notify debug` to show effective config and run `getMe`

## Security

Telegram bot tokens are sensitive. Prefer env vars if you don’t want tokens persisted in plaintext.

## License

MIT — see `LICENSE`.