pi-telegram-notifier

Telegram notifications for final Pi agent responses and provider balances

Packages

Package details

extension

Install pi-telegram-notifier from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:pi-telegram-notifier

Package: pi-telegram-notifier
Version: 0.1.6
Published: Sep 29, 2026
Downloads: 1,140/mo · 1,140/wk
Author: gybra
License: MIT
Types: extension
Size: 29.2 KB
Dependencies: 0 dependencies · 1 peer

Pi manifest JSON

{
  "extensions": [
    "./extensions/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

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

In Pi, run /telegram-pair.
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.
`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.