pi-telegram/README.md

pi-telegram

Full pi build session: View the session transcript, which captures the full pi session in which pi-telegram was built.

Telegram DM bridge for pi.

Install

From git:

pi install git:github.com/llblab/pi-telegram

Or for a single run:

pi -e git:github.com/llblab/pi-telegram

Configure

Telegram

1. Open @BotFather
2. Run /newbot
3. Pick a name and username
4. Copy the bot token

pi

Start pi, then run:

/telegram-setup

Paste the bot token when prompted.

The extension stores config in:

~/.pi/agent/telegram.json

Connect a pi session

The Telegram bridge is session-local. Connect it only in the pi session that should own the bot:

/telegram-connect

To stop polling in the current session:

/telegram-disconnect

Check status:

/telegram-status

Pair your Telegram account

After token setup and /telegram-connect:

1. Open the DM with your bot in Telegram
2. Send /start

The first DM user becomes the allowed Telegram user for the bridge. The extension only accepts messages from that user.

Usage

Chat with your bot in Telegram DMs.

Send text

Send any message in the bot DM. It is forwarded into pi with a [telegram] prefix.

Send images and files

Send images, albums, or files in the DM.

The extension:

• downloads them to ~/.pi/agent/tmp/telegram
• includes local file paths in the prompt
• forwards inbound images as image inputs to pi

Ask for files back

If you ask pi for a file or generated artifact, pi should call the telegram_attach tool. The extension then sends those files with the next Telegram reply.

Examples:

• summarize this image
• read this README and summarize it
• write me a markdown file with the plan and send it back
• generate a shell script and attach it

Stop a run

In Telegram, send:

stop

or:

/stop

That aborts the active pi turn.

Queue follow-ups

If you send more Telegram messages while pi is busy, they are queued and processed in order.

The pi status bar shows queued Telegram turns as compact previews, for example:

+3: [summarize this image…, write a shell script…, 📎 2 attachments]

Each preview is limited to at most 5 words or 40 characters.

Reprioritize or discard queued messages

While a message is still waiting in the queue:

• React with 👍 to move it into the priority block
• React with 👎 to remove it from the queue

Priority is stable:

• The first liked queued message stays ahead of later liked messages
• Removing 👍 sends the message back to its normal queue position
• Adding 👍 again gives it a fresh priority position

For media groups, a reaction on any message in the group applies to the whole queued turn.

Message reactions depend on Telegram delivering message_reaction updates for your bot and chat type.

Streaming

The extension streams assistant text previews back to Telegram while pi is generating.

It tries Telegram draft streaming first with sendMessageDraft. If that is not supported for your bot, it falls back to sendMessage plus editMessageText.

Notes

• Only one pi session should be connected to the bot at a time
• Replies are sent as normal Telegram messages, not quote-replies
• Long replies are split below Telegram's 4096 character limit
• Outbound files are sent via telegram_attach

License

MIT