pi-telegram/README.md

# pi-telegram

![pi-telegram screenshot](screenshot.png)

Telegram DM bridge for pi.

This repository is a fork of the original [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram).
It started from upstream commit [`cb34008460b6c1ca036d92322f69d87f626be0fc`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
- then llblab did a bunch of work in llblab
- then wassname:
    - show tool calls and thinking

## Start Here

- [Project Context](./AGENTS.md)
- [Open Backlog](./BACKLOG.md)
- [Changelog](./CHANGELOG.md)
- [Documentation](./docs/README.md)

## What Changed In This Fork

Compared to upstream commit `cb34008`, this fork significantly extends and hardens the extension.

- Better Telegram control UI, including an improved `/status` view with inline buttons for model and thinking selection, and trace display controls for thinking/tool-call blocks
- Interactive model selection improvements, including scoped model lists, thinking-level control for reasoning-capable models, and in-flight restart on a newly selected model for active Telegram-owned runs
- Queueing and interaction upgrades, including queue previews, reaction-based prioritization/removal, media-group handling, high-priority control actions, and safer dispatch behavior
- Markdown and reply rendering improvements, with richer formatting support, narrow-client-friendly table/list rendering, quote compatibility fixes, and multiple fixes for incorrect Telegram rendering and chunking edge cases
- Streaming, attachment, and delivery workflow hardening, including more robust preview updates and file handling
- General runtime polish, bug fixes, and refactors across pairing, command handling, and Telegram session behavior
- Cleaner internal domain layout, with flat `/lib/*.ts` modules and mirrored `/tests/*.test.ts` suites that use repo-scoped domain names

In short: this fork is no longer just a repackaged copy of upstream; it is a feature-expanded and bug-fixed Telegram frontend for pi.

## Install

From npm:

```bash
pi install npm:@llblab/pi-telegram
```

From git:

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

Or for a single run:

```bash
pi -e @llblab/pi-telegram
```

## Configure

### Telegram

1. Open [@BotFather](https://t.me/BotFather)
2. Run `/newbot`
3. Pick a name and username
4. Copy the bot token

### pi

Start pi, then run:

```bash
/telegram-setup
```

Paste the bot token when prompted.
If a bot token is already saved in `~/.pi/agent/telegram.json`, `/telegram-setup` shows that stored value by default. Otherwise it pre-fills from the first configured environment variable in `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, or `TELEGRAM_KEY`.

After the bot token, `/telegram-setup` asks for your numeric Telegram user ID if one is not already configured. To find your ID: DM [@userinfobot](https://t.me/userinfobot) on Telegram — it replies with your numeric ID. This is your permanent account ID, not your `@username` (mutable) or phone number (never visible to bots).

You can also pre-configure the allowed user ID via the environment variable `TELEGRAM_ALLOWED_USER_ID`:

```bash
export TELEGRAM_ALLOWED_USER_ID=123456789
```

The env var takes precedence over the saved config file on every session start. Only one user ID is supported.

The extension stores config in:

```text
~/.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:

```bash
/telegram-connect
```

To stop polling in the current session:

```bash
/telegram-disconnect
```

Check status:

```bash
/telegram-status
```

## Allowed Telegram user

The bot only accepts messages from the pre-configured allowed user. Polling will not start until an allowed user ID is configured.

If any other Telegram account messages the bot, the bot replies with an authorization error and logs the sender's numeric user ID to the pi TUI (as a warning) so you can identify it if needed.

## Usage

Chat with your bot in Telegram DMs.

Additional fork-specific controls:

- `/start` shows help and refreshes Telegram's bot command menu with local bridge controls plus Telegram-valid pi prompt, skill, and extension commands such as `/p`
- `/status` now has a richer view with inline buttons for model and thinking controls, and joins the high-priority control queue when pi is busy
- `/model` opens the interactive model selector, applies idle selections immediately, joins the high-priority control queue when pi is busy, and can restart the active Telegram-owned run on the newly selected model, waiting for the current tool call to finish when needed
- `/compact` starts session compaction when pi and the Telegram queue are idle
- `/trace` cycles Telegram trace display mode: `text` hides trace blocks, `compact` shows shortened trace blocks with an explicit truncation notice, and `full` shows the complete final trace
- Queue reactions: `👍` prioritizes a waiting turn, `👎` removes it

### 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:

```text
stop
```

or:

```text
/stop
```

That aborts the active pi turn.

If pi becomes locally idle but the Telegram bridge still holds stale local state for the aborted turn, the next Telegram message clears that stale state and resumes normal dispatch.

### 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:

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

Priority turns promoted with 👍 are marked with `⬆` in that queue preview.

Each preview is limited to at most 4 words or 32 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`.

Compact trace mode marks shortened thinking/tool blocks explicitly instead of silently cropping them. Full trace mode keeps complete trace content, includes tool results, and uses a tool's saved full-output file when pi provides one.

Direct `!` shell command replies are delivered in full across Telegram-safe chunks instead of being cut to the first screenful.

Telegram's bot command menu is refreshed by `/start`. The bridge publishes its local controls first, then any pi prompt, skill, or extension commands whose names are accepted by Telegram's Bot API.

## 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