pi-telegram-notifier

Send the final response of each Pi agent run to a paired private Telegram chat. Each notification contains a UTC timestamp, device hostname, provider, full response text, and the actual remaining provider balance when it can be queried. Telegram metadata (provider and quota) is in English; the agent's response is forwarded verbatim in its original language. Intermediate tool calls do not trigger messages.

Install and configure

Requires Node.js 22.19+ and Pi. Install the published package, create a Telegram bot using @BotFather, and set its token outside the repository before starting Pi:

pi install npm:pi-telegram-notifier
export PI_TELEGRAM_BOT_TOKEN='your-bot-token'
pi

Update or reload Pi

If Pi is already running, run /reload after installing the package (restart Pi if you just set the token). To update a published install later, run pi update npm:pi-telegram-notifier. If you previously installed a local checkout, run pi list, then pi remove /absolute/path/to/pi-telegram-notifier to avoid loading both copies.

Pair a private chat

1. In Pi, run /telegram-pair.
2. In a private chat, send the bot the displayed /start <code> within five minutes.

During pairing, the bot must receive updates through getUpdates; disconnect any webhook or other updates consumer first. If pairing fails, the existing chat remains paired.

Check pairing status

In Pi, run /telegram-status to see whether the bot token is configured and a private chat is paired. This reports saved local state; it does not check live Telegram connectivity.

Switch chats and pairing storage

Run /telegram-pair again to switch chats. The extension stores only the numeric chat ID in ~/.pi/agent/pi-telegram-notifier.json (or $PI_CODING_AGENT_DIR/pi-telegram-notifier.json), with mode 0600. Pairing uses getUpdates only during setup; there is no always-on polling afterward.

Privacy: final agent responses and the device hostname are sent to Telegram. Responses can contain sensitive text; only use this package if that is acceptable for your projects and Telegram chat. Bot and provider tokens are not stored in the package or sent as message text. Telegram Bot API uses the bot token in the request URL; do not log outgoing URLs. Keep your shell environment and Pi credentials private. A lost or compromised Telegram bot token must be revoked with BotFather.

Quota coverage

The quota/credit field supports these Pi provider IDs (using the credential Pi resolves for the active model):

| Pi provider ID | Mode | Required credential | What is shown | | --- | --- | --- | --- | | openai-codex | Subscription | ChatGPT OAuth | Remaining 5h / 7d usage-window percentages; official Codex client endpoint. | | openai | Subscription (Codex fallback) | ChatGPT OAuth and a separate openai-codex OAuth login | Codex account windows, explicitly labeled (Codex login), not the new login's app-specific limit. The new ChatGPT token cannot read this endpoint. Log both providers into the same account; without the Codex login, Quota unavailable. API keys are not supported. | | anthropic | Subscription | Claude OAuth | Remaining 5h / 7d usage-window percentages; private OAuth endpoint. | | claude-bridge (pi-claude-bridge) | Subscription | Pi's Claude OAuth (/login → Anthropic) | Same 5h / 7d windows as anthropic: the bridge has no credential of its own, so the matching anthropic model's OAuth login is used. Log Pi and Claude Code into the same Anthropic account, otherwise Pi's account quota is shown. Without the login, Quota unavailable. | | xai | Subscription | Grok OAuth | Remaining weekly shared Grok credits percentage, not prepaid API credit; official Grok client endpoint. | | zai | Subscription (Coding Plan) | Z.ai Coding Plan key | Remaining 5h model quota percentage; Z.ai usage plugin endpoint. Not the separate MCP tool quota. | | zai-coding-cn | Subscription (Coding Plan) | China Coding Plan key | Same model quota on open.bigmodel.cn. | | openrouter | API credit | Management key | Remaining account credits in USD; ordinary inference keys cannot access the credits endpoint (HTTP 403). Per-key spending limits are not account credit. | | deepseek | API credit | API key | Available CNY/USD balance via /user/balance. | | moonshotai | API credit | API key | Available USD balance via /v1/users/me/balance. | | moonshotai-cn | API credit | API key | Available CNY balance via /v1/users/me/balance. |

Not supported as API credit: an openai API key does not expose a verified remaining-balance endpoint; an anthropic API key does not expose its subscription quota or a verified remaining API credit; an xai API key does not expose Grok subscription quota or the prepaid API balance (the latter requires a separate management key and team ID); Z.ai pay-as-you-go keys may have no Coding Plan quota. None of the listed providers currently supports both subscription quota and API credit through this extension. Usage/cost reports and spending caps are not remaining credit.

Pi resolves and refreshes provider credentials, including those saved in its auth.json; this extension does not read that file. The Codex, Claude, Grok and Z.ai quota endpoints above are not guaranteed stable public APIs. All other providers, custom/proxied endpoints, inaccessible credentials, and failed or malformed lookups show Quota unavailable without blocking the notification. Quota percentage is not inferred from context-window usage, token usage, or request rate limits. See the 41-provider inventory for sources and limitations.

Telegram has a message-length limit; long responses are delivered in consecutive plain-text chunks. If delivery fails, Pi reports a generic failure without leaking message or credentials. Network requests have timeouts; Pi remains usable.

Develop and release

npm ci
npm run typecheck
npm test
npm pack --dry-run --json
pi --no-extensions -e . --help

Read AGENTS.md before editing. Open contributions with tests for behavior changes and official provider documentation for balance integrations. MIT licensed; see LICENSE. CI runs tests and packaging checks. The published npm package includes the pi-package keyword for the Pi package gallery. New versions are released manually; CI does not publish packages or handle real credentials.