pi-telegram

A Telegram companion hub for live Pi sessions.

pi-telegram turns a private Telegram DM into a mobile operator surface for Pi. It accepts prompts, queues work, streams readable previews, delivers final replies and files, exposes safe controls, and lets companion extensions add Telegram-native capabilities without owning a second bot loop.

It is a runtime adapter, not a remote terminal. Start or supervise work in the Pi TUI, then continue from Telegram while away from the keyboard. Each Telegram destination follows a running Pi instance and sends prompts into that instance's currently active session; it is not permanently bound to one session file or session identity. The bridge preserves Pi session semantics instead of pretending Telegram is a PTY, shell, process launcher, or session browser. That boundary is the product: Telegram gets safe runtime handles, not raw terminal power.

Every completed intermediate commentary block from a Telegram-originated turn is delivered once as its own message before the existing final reply. Proactive push is enabled by default for local, autonomous, and unclassified extension follow-up work: assistant.proactivePush projects visible checkpoints and the final answer to the authorized Telegram target once and in order, preserving assistant-authored telegram_button comments as interactive prompt buttons; set it explicitly to false to disable only that local/autonomous projection. Neither path mirrors local prompts, thinking, tool traffic, token deltas, or stale-generation work. The separate Activity setting defaults to verbose so new installations discover collapsed provider-exposed thinking and tool evidence immediately; operators can narrow it to one class or choose quiet. See Outbound and the configuration reference.

This repository is an actively maintained fork of badlogic/pi-telegram. It started from upstream commit cb34008 and has since diverged substantially.

Install

From npm:

pi install npm:@llblab/pi-telegram

From git:

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

The 0.21 extension platform requires Pi 0.80.6 or newer. Its Activity API uses the public agent_settled lifecycle event to keep retries/continuations under one activity identity and release that identity only after the run fully settles.

Pi is the primary and only officially supported host. Narrow host-neutral adapters preserve ordered prompt blocks and normalize synchronous or asynchronous legacy/generic settings services for Pi-compatible hosts, but this is best-effort compatibility rather than an OMP support guarantee. Alternate-host shims must still reproduce required Pi lifecycle semantics—especially agent_settled—and their maintainers own ongoing validation.

Quick Start

1. Create a Telegram bot

1. Open @BotFather. BotFather's chat commands and Mini App are different surfaces; Telegram Desktop supports the Mini App through Open App / Menu in the BotFather profile.
2. Run /newbot.
3. Pick a name and username.
4. Copy the bot token.

2. Configure Pi

Run this inside Pi:

/telegram-setup

Paste the bot token. If ~/.pi/agent/telegram.json already contains a saved token, setup offers it as the default. If no saved token exists, setup can prefill from TELEGRAM_BOT_TOKEN, TELEGRAM_BOT_KEY, TELEGRAM_TOKEN, or TELEGRAM_KEY. Bot/session identity persists under profiles.default; shared handlers and assistant/voice/time settings remain top-level. /telegram-setup default and /telegram-connect default are exact aliases for the bare commands. Use /telegram-setup <name> only when you want an additional bot profile. Cancelling or failing named-profile token validation leaves the currently active profile and polling runtime unchanged; setup reports the profile as saved and connected only after polling startup succeeds.

3. Connect this Pi instance and its active session

/telegram-connect

The connected Pi instance owns Telegram polling. Use /telegram-connect <name> to activate a named profile. Each profile is a parallel bot runtime with isolated polling, diagnostics, Threaded Mode state, and local bus transport; the default profile keeps unsuffixed runtime paths. In classic mode each profile uses a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the profile's leader and later visible Pi instances register as followers.

After an unclean computer shutdown, /telegram-connect detects truncated or structurally invalid temporary ownership/routing files, quarantines only the damaged files under tmp/telegram/recovery/, and retries once. A journal snapshot removed by older broad temp cleanup is rebuilt when its complete segment history proves an empty result, while a revisionless snapshot is repaired from the first surviving segment's exact predecessor when the reconstructed tail validates. Otherwise the snapshot and segments are quarantined as recovery evidence, a fresh journal is published, and startup continues with an informational diagnostic instead of requiring manual JSON repair. Saved telegram.json configuration and runtime diagnostics remain intact. Recovery never replaces a verifiable live owner; if safe automatic recovery cannot complete, the command gives one explicit Pi-restart instruction instead of requiring deletion of the whole tmp/ directory.

4. Pair your Telegram account

Open the bot DM and send:

/start

The first Telegram user to message the bot becomes the allowed owner. Other users are ignored. This is a first-contact security boundary: keep the bot private and send /start immediately after connecting. For stricter setup, restrict access to your account in the BotFather Mini App when that control is available, or preconfigure your numeric Telegram user id as profiles.default.allowedUserId in the existing ~/.pi/agent/telegram.json before connecting (preserve the saved botToken and any other settings):

{
  "profiles": {
    "default": {
      "botToken": "<existing-token>",
      "allowedUserId": 123456789
    }
  }
}

After required pairing state is persisted, /start is admitted independently from best-effort menu rendering and BotFather command-list synchronization, so either Telegram side effect can fail or remain in flight without stopping later inbound updates.

5. Enable optional bot capabilities in BotFather

Enable the optional capabilities the bridge needs in the @BotFather Mini App. On Telegram Desktop, open the BotFather profile and use Open App / Menu, select the configured bot, open Settings, and toggle Threaded Mode there rather than relying only on the inline chat-command interface. The bridge does not fail loudly when a capability is off; the feature simply never triggers.

1. Enable guest mode so the bot can answer mentions and replies in chats where it is not a member.
2. Enable private-chat Threaded Mode; when it is available, one live instance becomes the profile's leader and later visible Pi instances register as followers. Without it, the bridge stays in classic single-owner DM mode.
3. Make the bot an administrator in any chat where the queue reaction shortcuts should work. Reaction updates require admin rights, so the shortcuts silently do nothing in non-admin chats; private chats deliver reactions without admin rights.

What It Feels Like

• Start a task in the terminal, walk away, and keep supervising it from your phone.
• Send another prompt while Pi is busy; it becomes a queued Telegram turn instead of interrupting the active run.
• Open /start to inspect status, model, thinking, settings, prompt templates, and queue controls.
• Send voice, images, files, replies, edits, or media groups; the bridge turns them into Pi context.
• Ask for an artifact; telegram_attach returns it through the active reply or direct Telegram delivery.
• In Threaded Mode, run multiple visible Pi instances through one bot, each with its own Telegram thread.
• Configure named profiles to run independent Telegram bots from the same Pi agent directory without sharing transport or routing state.

Product Model

Feature Showcase

pi-telegram is intentionally broad: it is a Telegram-shaped runtime surface, not only a message relay. This catalogue keeps the practical feature surface visible while detailed contracts stay in /docs.

Core Loop

Telegram message
  -> Telegram turn
  -> queue or active dispatch
  -> Pi agent lifecycle
  -> streaming preview / native active status
  -> final Rich Markdown reply
  -> optional files, voice, buttons, or callback actions

The bridge keeps Telegram responsive without stealing Pi's runtime model. Queueing, model changes, compaction, aborts, final delivery, and direct artifact sends all stay scoped to the Pi instance that accepted the work.

Telegram Controls

Use these in the bot DM.

Hidden compatibility shortcuts: /help, /status, /model, /thinking, /queue, and /settings jump into the same menu system.

Pi Commands

Run these inside Pi.

Named profile identifiers contain only lowercase ASCII letters and digits (maximum 32 characters); default, main, and active remain reserved. If graceful thread deletion was interrupted, a same-profile replacement reuses its still-active thread and cancels the superseded cleanup instead of deleting and recreating the tab during startup.

Main Surfaces

Operator Menu

/start opens the Telegram-native control panel: status, prompt-template commands, model selection, thinking level, settings, queue controls, and extension sections. It is the primary Telegram UI; reaction shortcuts are secondary queue affordances.

Queue Runtime

Messages sent while Pi is busy become queued turns. Queue controls let you inspect, prioritize, keep or skip, and dispatch work without touching the terminal.

Queue policy:

• One prompt is one queue object with exactly one current lane and one current position; it never reserves a shadow place in the other lane.
• Priority and Normal are separate FIFO lanes; Priority dispatches first.
• Moving Normal → Priority removes the prompt from Normal and places it at the Priority tail. Moving Priority → Normal removes it from Priority and places it at the Normal tail; no former position is restored.
• Keep/Skip never changes lane position. Skip remains reversible while waiting and drops the prompt without a model turn only when dispatch reaches it.
• Reactions control two independent dimensions; changing one category preserves the other:
  • Positive: 👍, ⚡️, ❤️, 🕊, 🔥 — controls Priority.
  • Negative: 👎, 👻, 💔, 💩, 🗑 — controls Skip.
• Priority and Skip can coexist—for example 👍 + 💩. Skip wins at dispatch, regardless of which negative emoji is selected.
• Menu selectors and reactions share queue state, but the bot cannot remove a user's reaction; Keep may clear internal Skip while the user's emoji remains visible until they remove it.

The detailed contract lives in Priority, Reactions, Keep, and Skip. If Pi automatically retries a transient provider failure, the active Telegram turn stays bound until the successful reply arrives or Pi confirms that the run has settled.

Native Rich Markdown

Rich Markdown is the default model-answer membrane. Complete assistant and guest model replies use Telegram's native Rich Message APIs. Activity thinking uses persistent headerless expandable HTML, while each completed tool uses one iconless native Rich root details node whose arguments open with the root while secondary JSON evidence stays collapsed; thinking, tools, and verbose select the visible classes, while menus, status rows, queue controls, settings, diagnostics, and other operational UI retain explicit Telegram HTML/plain rendering. Three Settings controls keep the layers separate: Draft previews toggles streamed answer drafts, Activity chooses quiet or verbose technical activity, and Assistant rendering chooses final-answer delivery (rich Native Rich Markdown or html legacy Markdown-to-HTML).

Files And Artifacts

Inbound files land under <agent-dir>/tmp/telegram and default to a 50 MiB limit. telegram_attach is the canonical outbound file path. During Telegram-originated turns it attaches to the active reply; during explicit local/TUI delivery it can send to the paired/default chat or routed Threaded Mode target.

Voice And Media

Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured outboundHandlers or registered TTS providers; pi-telegram owns reply policy and Telegram transport, while providers own synthesis. Configure provider-neutral local/API pipelines and ordered fallbacks through telegram.json command templates. The default hidden reply mode still supports intentional voice delivery through explicit telegram_voice actions; mirror and always add automatic voice policy. Explicit actions accept either a JSON object or compact double-quoted attributes, with equivalent text and value payload keys and one colon-free action marker.

Buttons And Callbacks

Assistant replies can include top-level hidden telegram_button comments using a JSON object, adaptive JSON/CML matrix, positional Compact Matrix Literal (CML), or compact double-quoted attributes; telegram_buttons is a plural alias. One adaptive matrix may mix named JSON objects with positional CML cells, and commas between completed matrix or row elements are optional while JSON object internals remain strict. Top-level cells become full-width rows while nested rows group one or more buttons horizontally without an artificial parser-level width cap; generated surfaces default to five columns and use six to eight only for short position-bearing labels. CML uses {value}, {label|prompt}, or {label|prompt|selected_style} with primary, success, or danger; the optional style requires an explicit prompt. It trims atom boundaries, preserves non-structural text literally, and decodes only \|, \}, and \\. Prefer one matrix comment for multiple buttons. Buttons use label plus prompt, or the compact value key when both are identical. The action marker is colon-free for every payload form. The bridge strips the comments from visible text, renders inline buttons, and routes callbacks back into Pi as queued prompts or extension-owned callback actions. Button-only replies receive the standard ☑️ **Choose an option:** heading as automatic visible fallback text. Once a generated prompt button is accepted, only that exact button switches to its optional selected_style (primary blue by default, success green, or danger red) without altering its agent-authored label or emoji; every style still queues the selected prompt.

Threaded Mode And Multi-Instance Bus

Classic private DM mode is the base product mode. When Telegram private-chat Threaded Mode is available, the bridge enables a local leader/follower bus automatically:

• One live leader owns getUpdates.
• Followers are visible Pi processes started by the operator.
• Each connected instance gets a Telegram thread target.
• Queued work for a live follower transfers through authenticated exact-journal handoff rather than replaying under the transport owner.
• Follower session replacement automatically reconnects the new session context to the same thread instead of requiring another manual connect.
• Unknown threads are preserved and offered explicit reroute/restore choices.
• Telegram never launches hidden Pi processes.

Environment Configuration

Most controls live in Pi commands or the Telegram menu. Environment variables remain for bootstrap and transport boundaries:

Defaults are chosen for ordinary private-bot use: saved config in ~/.pi/agent, inbound temp files in ~/.pi/agent/tmp/telegram, assistant: { rendering: "rich", draftPreviews: false, activity: "verbose", timeInjection: "interval" } for assistant output and activity, and native Telegram active status for long-running turns.

Extension Platform

Companion extensions can integrate with Telegram without owning polling or transport:

• Register Telegram slash commands.
• Add menu sections and settings surfaces.
• Add compact status rows.
• Deliver target-aware operational views and chat actions from companion code.
• Observe normalized assistant, thinking, tool, compaction, and settlement activity without blocking Pi.
• Handle update/callback namespaces.
• Provide inbound preprocessing handlers.
• Provide outbound voice synthesis.
• Use direct delivery helpers for explicit local/TUI sends.

Stable public entrypoints are documented in Public API, Telegram Delivery API, Telegram Activity API, Extension Sections, Inbound Handlers, Outbound Handlers, Updates, and Voice Integration.

Safety Boundaries

Durable inbound admission is a process-crash recovery guarantee. Atomic private-file replacement preserves acknowledged journal authority across ordinary process exit, crash, kill, and replacement, but the extension does not flush files or parent directories for host/kernel/filesystem/device/power-loss durability. Keep ~/.pi/agent on appropriately managed storage and backups if that stronger operational guarantee is required. Before downgrading below 0.28.0, run node scripts/check-downgrade.mjs; a blocked result means 0.28.x must drain the retained journal first. See Durable Admission And Recovery.

pi-telegram intentionally does not:

• Spawn hidden Pi follower processes.
• Pretend Telegram is a terminal or PTY.
• Forward arbitrary Telegram slash commands into the Pi TUI.
• Inject raw TTY input or terminal-control sequences.
• Replace Pi session lifecycle without an official Pi API.
• Let non-owner Telegram users control the bridge.

Telegram is a companion surface around a live Pi runtime, not a second runtime. It can compact the current session, but it cannot create, resume, fork, browse, or switch sessions until Pi exposes safe public extension APIs for those operations.

A Telegram prompt is a normal model turn in the active Pi session and therefore inherits that session's active post-compaction context; the bridge does not make token cost proportional only to the new mobile message. The bundled telegram-bridge Skill owns general agent operation, generated-control-surface proactively compiles optional evidence-backed ephemeral controls when model interpretation remains useful, and generative-apps compiles stable repeated interaction into reviewed reusable applications whose bound buttons bypass model inference while ordinary prompt buttons retain it. Generative Apps may own a closed state machine or adapt another authoritative tool, service, Actor Run, or application through bounded methods. Disconnecting removes pi-telegram's delivery tools and transient routing guidance from later requests until direct ownership or follower registration returns, without changing other active Pi tools. Pi session JSONL contains model history; profile-scoped pi-telegram logs*.jsonl contains redacted operational events and is never model context.

Documentation Map

• Architecture — runtime, domains, queue, transport, and Threaded Mode overview.
• Public API — package entrypoints and stable companion-extension contracts.
• Telegram Delivery API — target-aware operational views, logical message handles, and lifecycle-safe transport.
• Telegram Activity API — normalized lifecycle events, source identity, non-blocking delivery contexts, and consumer policy examples.
• Inbound Handlers — Telegram-to-Pi preprocessing pipelines.
• Outbound Handlers — final text/voice/file transformation and delivery.
• Voice Integration — STT/TTS provider model and reply policies.
• Extension Sections — Telegram-native companion UI surfaces.
• Updates — update handler registry and callback interop.
• Multi-Instance Bus — leader/follower routing in Threaded Mode.
• UI Style — menu, emoji, labels, dialogs, and inline keyboard standards.
• Callback Namespaces — callback ownership and routing.
• Command Templates — handler command-template conventions.
• Generative Apps — reusable application identity, state, generated button views, hybrid action routing, replacement, and bounded execution contract.

The docs index lives at docs/README.md.

Development

npm run typecheck
npm test
npm run audit
npm run pack:check

Full validation:

npm run validate

npm run audit fails closed over dependencies owned and shipped by pi-telegram, omitting Pi host packages declared as peers because the host selects and supplies their dependency graph. Use npm run audit:host separately to inspect the complete installed development graph, including upstream Pi advisories; host findings remain visible without being misattributed to this extension's release artifact.

Project context:

• AGENTS.md — engineering and runtime conventions.
• BACKLOG.md — release-relevant open work.
• CHANGELOG.md — completed delivery history.