This repository is an actively maintained fork of badlogic/pi-telegram. It started from upstream commit cb34008460b6c1ca036d92322f69d87f626be0fc and has since diverged substantially.
- Priority Command Queue: Control commands such as
/statusand/modeluse a high-priority control queue, so they do not get stuck behind normal queued prompts when pi is busy. - Interactive UI: Manage your session directly from Telegram. Inline buttons allow you to switch models and adjust reasoning (thinking) levels on the fly.
- In-flight Model Switching: Change the active model mid-generation. The agent gracefully pauses, applies the new model, and restarts its response without losing context.
- Smart Message Queue: Messages sent while the agent is busy are queued and previewed in the pi status bar, and queued turns can be reprioritized or removed with Telegram reactions.
- Mobile-Optimized Rendering: Tables and lists are formatted for narrow screens, table padding accounts for emoji grapheme and wide Unicode display width, and Telegram-originated runs prompt the assistant to prefer narrow table columns for phone readability. Markdown is correctly parsed and split to fit Telegram's limits without breaking HTML structures or code blocks, block spacing stays faithful to the original Markdown with readable heading separation, supported absolute links stay clickable, and unsupported link forms degrade safely.
- File Handling & Attachments: Send images and files to the agent, or ask it to generate and return artifacts. Inbound downloads and outbound attachments are size-limited by default, and outbound files are delivered automatically via the
telegram_attachtool. - Streaming Responses: Closed Markdown blocks stream back as rich Telegram HTML while pi is generating, and the still-growing tail stays readable until the final fully rendered reply lands.
From npm:
pi install npm:@llblab/pi-telegramFrom git:
pi install git:github.com/llblab/pi-telegram- Open @BotFather
- Run
/newbot - Pick a name and username
- Copy the bot token
Start pi, then run:
/telegram-setupPaste your bot token when prompted. If a bot token is already saved in ~/.pi/agent/telegram.json, the setup prompt shows that stored value by default. Otherwise it prefills from the first configured environment variable in TELEGRAM_BOT_TOKEN, TELEGRAM_BOT_KEY, TELEGRAM_TOKEN, or TELEGRAM_KEY. The saved config file is written with private 0600 permissions.
/telegram-connectThe bridge is session-local. Only one pi session should be connected to the bot at a time.
- Open the DM with your bot in Telegram
- Send
/start
The first user to message the bot becomes the exclusive owner of the bridge. The extension will only accept messages from this user.
Once paired, simply chat with your bot in Telegram. All text, images, and files are forwarded to pi.
Use these inside the Telegram DM with your bot:
/start: Pair the first Telegram user when needed, register the bot command menu, and show help./help: Show the Telegram help text./status: View session stats, cost, and use inline buttons to change models./model: Open the interactive model selector./compact: Start session compaction (only works when the session is idle)./stop: Abort the active run.
Telegram command admission is explicit: /compact, /stop, /help, and /start execute immediately; /status and /model enter the high-priority control lane so they can run before normal queued prompts when pi becomes safe to dispatch.
Run these inside pi, not Telegram:
/telegram-setup: Configure or update the Telegram bot token./telegram-status: Check bridge status, connection, polling, execution, queue, and recent redacted runtime/API failure events./telegram-connect: Start polling Telegram updates in the current pi session./telegram-disconnect: Stop polling in the current pi session.
- If you send more Telegram messages while pi is busy, they enter the default prompt queue and are processed in order.
👍moves a waiting prompt into the priority prompt queue, behind control actions but ahead of default prompts. Removing👍sends it back to its normal queue position, and adding👍again gives it a fresh priority position.👎removes a waiting turn from the queue. Telegram Bot API does not expose ordinary DM message-deletion events through the polling path used here, so queue removal is bound to the dislike reaction.- For media groups, a reaction on any message in the group applies to the whole queued turn.
- If you edit a Telegram message while it is still waiting in the queue, the queued turn is updated instead of creating a duplicate prompt. Edits after a turn has already started may not affect the active run.
- Inbound images, albums, and files are saved to
~/.pi/agent/tmp/telegram, local file paths are included in the prompt, and inbound images are forwarded to pi as image inputs. Inbound downloads default to a 50 MiB limit and can be adjusted withPI_TELEGRAM_INBOUND_FILE_MAX_BYTESorTELEGRAM_MAX_FILE_SIZE_BYTES. - Queue reactions depend on Telegram delivering
message_reactionupdates for your bot and chat type.
If you ask pi for a file or generated artifact (e.g., "generate a shell script and attach it"), pi will call the telegram_attach tool, and the extension will send the file alongside its next Telegram reply. Outbound attachments default to a 50 MiB limit and can be adjusted with PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES or TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES.
The extension streams assistant previews back to Telegram while pi is generating.
Rich previews are sent through editable messages because Telegram drafts are text-only. Closed top-level Markdown blocks can appear with formatting before the answer finishes, while the still-growing tail remains conservative and readable until the preview is replaced with the fully rendered Telegram HTML reply. Editable preview messages are also attached as replies to the source Telegram prompt when possible.
The pi status bar shows queued Telegram turns as compact previews, for example:
+3: [⬆ write a shell script…, summarize this image…, 📎 2 attachments]
- Replies to Telegram prompts are sent as Telegram replies to the source message when possible; if the source message is unavailable, delivery falls back to a normal message
- Long replies are split below Telegram's 4096 character limit without intentionally breaking Telegram HTML formatting; only the first split message is attached as a Telegram reply to the source prompt
- Temporary inbound Telegram files are cleaned up on later session starts
MIT