pi-telegram-plus

Full Telegram control of pi coding agent — commands, interactive UI, model/session management, file transfer, and real-time streaming output, all from Telegram.

pi-telegram-plus is a pi extension that turns Telegram into a full-featured remote control surface for the pi coding agent. It's not just a notification bot — it mirrors the core pi TUI experience into Telegram, with interactive menus, inline keyboards, file attachments, and live agent output rendering.

Forked from jalyfeng/pi-telegram-plus — extended with Rich Message API, improved error handling, guardrails/ask-user-question custom UI support, and more.

---

Features

🤖 Bot Connectivity

• Long polling — receives messages and callback queries in real time
• Multi-instance safe — file-based polling lock prevents multiple pi instances from racing on the same bot token
• Automatic reconnection — exponential backoff on transient failures
• Bot command menu sync — automatically syncs available commands to Telegram's BotMenu (up to 100 commands)

🎮 Full Session Control

All pi session lifecycle commands available via Telegram:

Command	Description
/new	Start a new session
/fork	Fork from a previous user message
/clone	Clone at a previous user message
/tree	Navigate session tree
/resume	Resume a previous session
/compact	Compact session context
/name	Set or show session name
/session	Show session statistics

🧠 Model & Authentication Management

• /model — View available models / switch current model via interactive selection
• /scoped-models — Toggle scoped model sets
• /thinking — Adjust thinking level (off/minimal/low/medium/high/xhigh)
• /login — OAuth or API key authentication with full interactive flow
• /logout — Remove stored credentials

📨 Message Modes

Two modes for handling incoming messages while the agent is running:

• steer (default) — New messages inject into the current turn via streamingBehavior: "steer". The agent stays streaming while receiving new input.
• queue — Messages wait in a per-chat queue for the current turn to finish.

🖥️ Interactive Telegram UI

Full interactive UI components built on inline keyboards:

• Notify — status/error messages
• Confirm — Yes / No / Cancel buttons
• Input — text input with Cancel button; replies are captured as input
• InputSecret — same as Input, but the prompt message is auto-deleted after reply to protect sensitive data
• Select — paginated option list with Prev/Next navigation
• Editor — multi-line text input prompt
• Custom — routes external extension UIs (e.g. ask_user_question, guardrails prompts) through Telegram

🎨 Message Rendering

• Rich Message API — native Telegram markdown rendering via sendRichText/editRichText, no extra dependencies
• Tool execution rendering — Configurable level (hidden / brief / full) for tool call visibility
• Thinking rendering — Configurable level (hidden / brief / full) for agent thinking blocks
• Output splitting — Safe UTF-8-aware splitting at Telegram's 4096-byte limit
• Image output — Automatically sends agent-generated images as Telegram photos

📎 File Attachments

Upload (agent → Telegram):

• Custom tg_attach tool available to the agent
• Sends files/documents/photos to the active Telegram chat
• Size limit enforcement (default 50 MB)
• Sensitive path blocking (e.g., /etc, ~/.ssh)
• Automatic photo detection (jpg/png/webp → send as photo, fallback to document)

Download (Telegram → user → agent):

• Automatically saves incoming photos, documents, videos, audio, voice, stickers to the working directory
• Reports saved paths back to the user
• Handles name sanitization and deduplication

⚙️ Telegram-Specific Commands

Command	Description
/tg-setup	Configure Telegram bot token (first-time setup)
/tg-connect	Enable / start Telegram connection
/tg-disconnect	Disable / stop connection (keeps token)
/tg-config	Configure rendering levels and message mode
/tg-bind-cwd	Bind a workspace directory to a separate bot token
/tg-unbind-cwd	Remove workspace bot binding
/tg-list	List all Telegram bot bindings

🔧 Utility Commands

Command	Description
/cwd	Show current working directory
/cd	Switch pi working directory
/stop	Abort the current agent turn
/status	Show runtime snapshot (workspace, model, context, messages)
/settings	Open settings menu
/copy	Copy last assistant text
/export	Export session to HTML/JSONL
/import	Import a session JSONL file
/share	Export session for sharing (gist)
/reload	Reload extensions, skills, prompts
/quit	Shut down pi
/changelog	Show changelog link
/hotkeys	Show keyboard shortcuts reference

---

Installation

Prerequisites

• Node.js >= 22.19.0
• pi coding agent installed globally
• A Telegram bot token from @BotFather

Install via npm

pi install npm:@kdejaeger/pi-telegram-plus

Forked from jalyfeng/pi-telegram-plus — this fork is published on npm as @kdejaeger/pi-telegram-plus.

Or install from source

git clone https://github.com/kdejaeger/pi-telegram-plus.git
cd pi-telegram-plus
npm install
pi packages add .

Configure your Telegram bot

Start pi, then run:

/tg-setup

Paste your bot token when prompted. The bot will connect automatically.

Note: On first message from any user, pi-telegram-plus automatically authorizes that user ID. Only that user can control the bot afterward.

---

Configuration

Per-Workspace Bot Tokens

You can bind different bot tokens to different directories:

/tg-bind-cwd /path/to/project

This creates a workspace-specific binding in ~/.pi/agent/tg.json. Workspace bindings take priority over the global configuration.

Rendering & Mode Settings

Via interactive menu:

/tg-config

Or directly:

/tg-config tool brief       # Tool rendering: hidden | brief | full
/tg-config thinking full    # Thinking rendering: hidden | brief | full
/tg-config mode steer       # Message mode: queue | steer
/tg-config retry 3          # API retry count: 0-10
/tg-config status full      # TUI footer: hidden | minimal | brief | full

status level	Footer shows
hidden	No telegram+ status line
minimal	tg+ with state icon, no username
brief	telegram+ with state icon, no username
full (default)	telegram+ with state icon and @username

Logging

pi-telegram-plus writes diagnostic logs to a file-based JSON Lines logger:

• Location: ~/.pi/agent/logs/pi-telegram-plus-YYYY-MM-DD.log (one file per UTC day)
• Format: One JSON object per line — { "ts": "…", "level": "…", "msg": "…", "scope": "…", … }
• Levels: debug, info, warn, error — configurable via PI_TELEGRAM_PLUS_LOG_LEVEL env var
• Rotation: Files rotate at 10 MiB per day, keeping up to 5 rotated copies

View recent logs:

tail -f ~/.pi/agent/logs/pi-telegram-plus-$(date +%F).log | jq .

---

How It Works

┌─────────────────┐     Long Polling      ┌──────────────────────┐
│   Telegram Bot   │ ◄──────────────────► │  pi-telegram-plus    │
│  (api.telegram)  │     Callback Queries  │  (pi extension)      │
└─────────────────┘                       │                      │
        ▲                                 │  ┌────────────────┐  │
        │ Messages / Files                │  │  Controller     │  │
        │                                 │  │  ├─ handleMsg   │  │
  ┌─────────┐                            │  │  ├─ handleCB    │  │
  │  User    │                            │  │  └─ runPrompt   │  │
  │ (Telegram)│                           │  │                  │  │
  └─────────┘                            │  │  ┌─────────────┐ │  │
        ▲                                │  │  │ TelegramUI  │ │  │
        │ Streaming Output               │  │  │ (interactive)│ │  │
        │ Live Tool/Thinking Events      │  │  └─────────────┘ │  │
        │ File Attachments (tg_attach)   │  │                  │  │
        └───────────────────────────────────┤  ┌─────────────┐ │  │
                                          │  │  Renderer   │ │  │
                                          │  │  (Rich Msg  │ │  │
                                          │  │   API /     │ │  │
                                          │  │   Markdown) │ │  │
                                          │  └─────────────┘ │  │
                                          │         │         │  │
                                          │         ▼         │  │
                                          │  ┌─────────────┐  │  │
                                          │  │ pi Agent    │  │  │
                                          │  │ (session,   │  │  │
                                          │  │ models,      │  │  │
                                          │  │ tools, ...) │  │  │
                                          │  └─────────────┘  │  │
                                          └──────────────────────┘

Architecture Overview

• index.ts — Extension entry point. Wires all modules together and handles session_start/session_shutdown lifecycle events.
  • Registers the tg_attach tool (schema via typebox)
  • Imports and initializes all modules
• lib/telegram-api.ts — Raw Telegram Bot API client with retry logic, file upload/download, and Rich Message API (sendRichText/editRichText).
• lib/polling.ts — Long polling loop with multi-instance file lock. Re-reads config while holding the lock to prevent offset regressions.
• lib/controller.ts — Message routing: slash commands, text prompts, media attachments, callback queries. Routes custom extension UIs (guardrails, ask_user_question) to the Telegram UI runtime.
• lib/telegram-ui.ts — Interactive UI layer: notify, confirm, input, inputSecret, select (pagination), editor, and generic custom() handler for external extension UIs.
• lib/renderer.ts — Hooks into agent lifecycle events (agent_start, tool_execution_*, message_end) and streams rendered output to Telegram via the Rich Message API.
• lib/html.ts — HTML escaping utilities (for safe Telegram HTML mode fallback).
• lib/text-split.ts — UTF-8-safe text splitter for Telegram's 4096-byte message limit.
• lib/config.ts — Configuration persistence with file locking for concurrent-safe writes. Supports global + workspace scopes.
• lib/attachments.ts — tg_attach tool registration (TypeBox schema) and outbound attachment delivery.
• lib/logger.ts — File-based JSON Lines logger with rotation, used for debugging Telegram issues.
• lib/session-capture.ts — Monkeys patches AgentSession.bindExtensions to intercept session lifecycle and capture the active session reference.
• lib/status.ts — TUI status line integration showing connection state.
• lib/heartbeat.ts — Periodic typing indicator while processing.
• lib/menu-commands.ts — Builds and syncs the Telegram BotMenu command list.
• lib/callback-protocol.ts — Encodes/decodes inline button callback data.
• lib/command-parser.ts — Slash command parser & bot-username normalizer.
• lib/types.ts — All TypeScript interfaces & types.
• lib/commands/ — Command handler modules: model, session, auth (login/logout), lifecycle, settings, tg-config, telegram-commands, info.

---

Project Structure

pi-telegram-plus/
├── index.ts                     # Extension entry point
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── lib/
    ├── types.ts                  # All TypeScript interfaces & types
    ├── telegram-api.ts          # Telegram Bot HTTP API client
    ├── polling.ts                # Long polling with multi-instance lock
    ├── controller.ts                # Message router & prompt executor
    ├── telegram-ui.ts            # Interactive UI (notify, confirm, input, select, editor, custom)
    ├── renderer.ts               # Agent event → Telegram output renderer
    ├── html.ts                   # HTML escaping utilities
    ├── text-split.ts              # UTF-8-safe text splitter for 4096 byte limit
    ├── command-parser.ts         # Slash command parser & bot-username normalizer
    ├── config.ts                 # Configuration store (global + workspace scopes)
    ├── attachments.ts            # Outbound file attachment tool (tg_attach)
    ├── heartbeat.ts              # Typing indicator pulse
    ├── status.ts                 # TUI status line formatter
    ├── logger.ts                 # File-based JSON Lines logger with rotation
    ├── session-capture.ts        # Agent session capture & handler patching
    ├── menu-commands.ts          # Telegram BotMenu sync
    ├── callback-protocol.ts      # UI callback encoding/decoding
    ├── commands/
    │   ├── register.ts           # Command registry aggregator
    │   ├── model.ts              # /model, /scoped-models, /thinking
    │   ├── session.ts            # /new, /fork, /clone, /tree, /resume, /cd, /cwd, /name, /session
    │   ├── auth.ts               # /login (OAuth + API key), /logout
    │   ├── info.ts               # /status, /copy, /export, /import, /share, /changelog, /hotkeys
    │   ├── lifecycle.ts          # /compact, /reload, /stop, /quit
    │   ├── settings.ts           # /settings menu
    │   ├── tg-config.ts          # /tg-config
    │   └── telegram-commands.ts  # /tg-setup, /tg-connect, /tg-disconnect, /tg-bind-cwd, /tg-list
    └── __tests__/
        ├── attachments.test.ts
        ├── callback-protocol.test.ts
        ├── config.test.ts
        ├── controller.test.ts
        ├── html.test.ts
        ├── info-status.test.ts
        ├── status.test.ts
        ├── telegram-ui.test.ts
        └── text-split.test.ts

---

Development

# Type checking
npm run typecheck

# Run tests
npm test

# Watch mode
npm run test:watch

---

Security

• No secrets in source code — All bot tokens and API keys are read from ~/.pi/agent/tg.json and ~/.pi/agent/auth.json at runtime.
• File permissions — Configuration files are created with chmod 600 (owner-only access).
• Sensitive input protection — API key inputs use inputSecret which automatically deletes the user's message after reading.
• Attachment path safety — Outbound tg_attach blocks sensitive paths (/etc, ~/.ssh, etc.).
• Polling lock — File-based lock prevents multiple pi instances from polling the same bot token simultaneously.
• First-user authorization — The first Telegram user to message the bot is automatically authorized; subsequent users are rejected.

---

Changelog

See CHANGELOG.md.