pi-telegram-bot

Telegram bot exposing pi as a personal coding agent. Chat with pi in Telegram with streaming responses, tool execution, and model switching.

Setup

1. Create a Telegram bot

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token

2. Get your Telegram user ID

1. Message @userinfobot on Telegram
2. It will reply with your user ID (a number like 123456789)

3. Configure environment

cp .env.example .env
# Edit .env with your TELEGRAM_BOT_TOKEN and TELEGRAM_USER_ID

4. Install and run

npm install
npm start
# or
./start.sh

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | TELEGRAM_BOT_TOKEN | Yes | — | Bot token from BotFather | | TELEGRAM_USER_ID | Yes | — | Your Telegram user ID (security: bot only responds to you) | | PROVIDER | No | anthropic | LLM provider | | MODEL | No | claude-sonnet-4-5 | Model ID | | THINKING_LEVEL | No | off | Thinking level (off/minimal/low/medium/high/xhigh) | | MAX_SESSIONS | No | 10 | Maximum concurrent sessions | | SESSION_IDLE_TIMEOUT | No | 3600 | Seconds before idle sessions are reaped | | SESSION_DIR | No | ~/.pi/agent/sessions | Session storage directory | | STREAM_THROTTLE_MS | No | 1000 | Minimum ms between message edits (Telegram rate limit) | | TELEGRAM_MSG_LIMIT | No | 4000 | Max message length before splitting | | ACK_REACTION | No | 🦞 | Emoji reaction on received messages (set empty to disable) |

Commands

| Command | Description | |---|---| | /help | Show available commands | | /new | Start a fresh session (clears history) | | /cancel | Abort the current stream | | /status | Show session info (model, tokens, cwd) | | /model <name> | Switch model (no args = list available) | | /thinking <level> | Set thinking level | | /sessions | List all active sessions | | /cwd <path> | Change working directory | | /reload | Reload extensions and prompt templates | | /diff | Show git diff of uncommitted changes | | /compact | Compact conversation to free context | | /context | Show context window usage |

Unknown /commands are forwarded to pi as extension commands.

Features

• Streaming responses — Messages update in-place as tokens arrive, respecting Telegram's rate limit
• Ack reactions — Reacts to your message immediately so you know it was received
• Persistent sessions — Sessions survive bot restarts via on-disk registry
• Session management — Multiple concurrent sessions with idle timeout and auto-reaping
• File handling — Send photos/documents and they're saved to the session's working directory
• Tool activity — See what tools pi is using in real-time during streaming
• Context tracking — Warnings at 80% and 90% context usage
• Auto-diff — Automatic diff posting when pi modifies files
• Security — Only responds to your configured Telegram user ID

Architecture

index.ts              → Entry point, dotenv, signal handlers
telegram.ts           → grammY bot setup, message/command routing
thread-session.ts     → Wraps pi AgentSession with streaming
session-manager.ts    → Session lifecycle, limits, idle reaping
streaming-updater.ts  → Throttled message editing with chunking
commands.ts           → Telegram slash command handlers
config.ts             → Environment variable parsing
session-registry.ts   → Persistent session state across restarts
formatter.ts          → Markdown + tool call formatting
file-handling.ts      → Download Telegram files, vision extraction
diff-reviewer.ts      → Git diff generation and posting

Requirements

• Node.js >= 20
• A pi-coding-agent installation (@mariozechner/pi-coding-agent)
• Anthropic API key (or other LLM provider configured in pi)