pi-telegram

A Telegram DM bridge for pi — chat with your pi coding agent from anywhere through a Telegram bot. Based on badlogic/pi-telegram, rewritten with AI to better fit my personal preferences and needs.

Features

• Two-way Telegram ↔ pi bridge over long-polling getUpdates
• Streamed replies with live previews, including extended thinking (separated from the answer by 💭 / ✏️ markers); long answers grow incrementally instead of only appearing at the end
• Markdown rendering to native Telegram formatting (headings, bold, italics, links, inline & fenced code, blockquotes, lists, tables, task lists, footnotes, LaTeX), robust to partial mid-stream snippets
• Attachments in: photos, albums, documents, video, audio, voice, animations and stickers; images are inlined as image inputs, everything else is referenced by local path
• Attachments out: a telegram_attach tool lets the agent send generated files with its reply
• Tool call breadcrumbs: each tool call posts a 🔧 … Rich Message with its arguments and output in collapsible blocks, edited in place to ✅ / ❌ on completion
• Mid-turn steering: messages sent while the agent is busy are injected into the running turn
• Typing indicator while the agent is working
• Single-user authorization by Telegram user id

Telegram-side commands

Auto-published as the bot menu at boot. Anything else is forwarded to pi as a user turn.

| Command | Description | | ---------- | -------------------------------------------- | | /new | Start a new pi session | | /resume | List recent sessions; /resumeN to switch | | /stop | Abort the current turn | | /status | Model, token usage, cost and context window | | /compact | Compact the conversation | | /skills | List skills available to the agent |

Resuming a session echoes that session's last reply back to the chat, so it reflects where you left off (the TUI already shows the full history).

Differences vs. upstream badlogic/pi-telegram

| Area | Upstream | This fork | | --------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Setup & lifecycle | /telegram-setup / /telegram-connect / /telegram-disconnect commands; explicit per-session connect | No pi-side commands; you write ~/.pi/agent/telegram.json yourself, polling auto-starts per session | | Authorization | First DM user is auto-paired | First DM sender id is shown as a warning in pi; unauthorized senders receive no response | | Commands & bot menu | Telegram-side commands limited to /status, /compact, stop, /help, /start; no menu published | Adds /new, /resume, /skills and publishes the menu via setMyCommands; session switching from Telegram | | Concurrency | Extra messages while busy are queued and dispatched after the current turn ends | Extra messages are steered into the running turn | | Aborted-turn replay | After stop, queued messages are re-injected as a synthetic history block | No replay — stop just aborts | | Prompt prefix | Each message prefixed with [telegram], plus a system-prompt suffix | Forwarded as-is | | Rendering | Plain text only; URL preview cards enabled | Native Rich Message (sendRichMessage, GitHub-Flavored Markdown) for every outgoing message | | Streaming | Probes sendMessageDraft, falls back to sendMessage + editMessageText; previews truncated at 4096 chars, full answer only appears at agent_end | sendRichMessageDraft live previews committed with sendRichMessage; oversized previews are promoted into real messages mid-stream so long answers grow live | | Tool call breadcrumbs | None | 🔧 … Rich Message per tool call: summary line plus collapsible arguments + output, edited with ✅ / ❌ | | Thinking blocks | Stripped | Streamed, separated by 💭 / ✏️ markers | | Status bar | Rich colored status | Only transient polling errors |

Media-group debouncing and the telegram_attach tool surface match upstream. Internally the fork is split into small manager closures instead of a single file.

Install

Only one pi session should poll a given bot token at a time, so load this per-session instead of installing globally:

pi -e npm:@qusic/pi-telegram

To use the Git checkout instead:

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

Configure

1. Talk to @BotFather, run /newbot, copy the bot token.

2. Create ~/.pi/agent/telegram.json:

   { "botToken": "123456:ABC-your-token-here" }

3. Start pi — polling starts automatically.

4. DM your bot once. pi shows a warning with your Telegram user id; add "allowedUserId": <id> to the config and restart. The bot stays silent until authorized.

Usage

Just chat with your bot. Text becomes the next pi turn; photos/files are downloaded and referenced in the prompt (images also inlined); ask pi for an artifact and it can call telegram_attach to send files back; /stop aborts.

License

MIT. See LICENSE.