avtc-pi-notification

Bell and Telegram notifications on agent completion, errors, or attention needed — only fires when you're away; inter-extension attention API included.

Features

• Two independent channels — terminal bell and Telegram, each with its own configurable delay timer
• Smart cancellation — both timers cancel on keypress, terminal focus, or the agent continuing
• Inter-extension attention API — extensions blocking on user input (e.g. avtc-pi-ask-user-question) can request attention, which fires these same delayed notifications
• Environment variable support — Telegram token and chat ID can be provided via env vars instead of settings
• Force IPv4 — enabled by default to avoid WSL2 IPv6 connectivity issues
• Retry on transient errors — Telegram sends retry with exponential backoff (configurable max attempts, base delay, and delay cap); 4xx errors fail fast

Installation

pi install npm:avtc-pi-notification

Configuration

Settings live in ~/.pi/agent/settings.json under the "avtc-pi-notifications" key. Project-level overrides go in <project>/.pi/settings.json and win over global settings.

The agent directory can be customized via the PI_CODING_AGENT_DIR environment variable (defaults to ~/.pi/agent).

Settings reference

| Key | Type | Default | Description | |-----|------|---------|-------------| | bell | boolean | true | Enable/disable terminal bell | | bellDelay | string | "30s" | Delay before bell fires (e.g., "30s", "1m") | | bellCommand | string | (none) | Optional command to run with bell (useful on Windows/WSL2 + Alacritty) | | bellCommandTimeoutMs | number | 1500 | Timeout for bell command execution | | telegram.enabled | boolean | false | Enable/disable Telegram notifications | | telegram.token | string | (none) | Telegram Bot API token (or use TELEGRAM_BOT_TOKEN / PI_TELEGRAM_TOKEN env vars) | | telegram.chatId | string | number | (none) | Telegram chat ID (or use TELEGRAM_CHAT_ID / PI_TELEGRAM_CHAT_ID env vars) | | telegram.delay | string | "2m" | Delay before Telegram fires (e.g., "2m", "120s") | | telegram.timeoutMs | number | 5000 | HTTP request timeout for Telegram API calls | | telegram.forceIpv4 | boolean | true | Force IPv4 for Telegram API calls (avoids WSL2 IPv6 issues) | | telegram.maxRetries | number | 3 | Max retry attempts on transient errors (network, timeout, 5xx, 429) | | telegram.retryBackoffMs | number | 10000 | Base delay (ms) for exponential backoff between retries (delay = base × 2^attempt) | | telegram.maxRetryIntervalMs | number | 180000 | Upper bound (ms) on exponential backoff between retries (caps growth; Telegram 429 retry_after still honored) | | telegram.includePrompt | boolean | false | Include the first user prompt in the Telegram message | | telegram.includeToolErrors | boolean | true | Include up to 3 recent tool errors in the message | | telegram.includeLeaf | boolean | false | Include subagent leaf ID in the message | | telegram.includeStarted | boolean | false | Include session start timestamp in the message |

Minimal Telegram config

{
  "avtc-pi-notifications": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABCDEF...",
      "chatId": "123456789"
    }
  }
}

Optional bell + Windows sound

{
  "avtc-pi-notifications": {
    "bell": true,
    "bellDelay": "30s",
    "bellCommand": "powershell.exe -NoProfile -Command \"[System.Media.SystemSounds]::Asterisk.Play()\"",
    "bellCommandTimeoutMs": 1500
  }
}

How delays work

On agent finish — or when attention is needed — both timers start and run independently:

1. Bell fires at 30s — you may be in another window; the bell brings you back.
2. Telegram fires at 2m — you're truly away from the computer.

Either timer is cancelled if you press a key, focus the terminal, or the agent continues.

Commands

| Command | Description | |---------|-------------| | /notification:notify | Send a test notification (bell + Telegram if configured) | | /notification:notify debug | Show effective config and run Telegram getMe to verify credentials |

Inter-extension API

If your extension blocks on user input (permission dialogs, question prompts, etc.), it can request attention so the user gets notified while away. Integration is three steps:

1. Copy the snippet — vendor src/snippets/canonical/subscribe-to-notifications.ts into your extension (e.g. src/snippets/vendored/subscribe-to-notifications.ts).

2. Register it in your entry point:

   import { subscribeToNotificationApi, withAttention } from "./snippets/vendored/subscribe-to-notifications.js";
   
   export default function (pi: ExtensionAPI) {
     subscribeToNotificationApi(pi);
     // ...
   }

3. Wrap any blocking UI call with withAttention(source, detail, fn) — it requests attention on entry and cancels on completion or error. If pi-notification isn't installed, it's a transparent no-op:

   const choice = await withAttention("my-extension", "branch selection", () =>
     ctx.ui.select("Select a branch:", branches)
   );

Security

Telegram bot tokens are sensitive. Prefer env vars if you don't want tokens persisted in plaintext settings files. Four env vars are supported:

| Env var | Purpose | |---------|---------| | TELEGRAM_BOT_TOKEN | Telegram Bot API token | | PI_TELEGRAM_TOKEN | Alternative Telegram Bot API token | | TELEGRAM_CHAT_ID | Telegram chat ID | | PI_TELEGRAM_CHAT_ID | Alternative Telegram chat ID |

The PI_* variants are provided for environments where the shorter names conflict with other tools.

Full suite

Check out the full suite of related extensions, avtc-pi — deterministic feature development, subagent delegation, working-memory, behavioral learning, parallel-work guardrails, durable decisions, notifications, and more.

Developed with Z.ai — get 10% off your subscription via this referral link.

Attribution

An evolution of lsj5031/pi-notification-extension.

License

MIT