oh-my-pi-telegram/README.md

Issues · Docs · Changelog · Backlog

What it is

oh-my-pi-telegram is an Oh My Pi (omp) extension that turns a private chat with your own Telegram bot into a companion for the session running on your machine. From the phone you send prompts, files and voice notes, queue and steer turns, switch the model or thinking level, and receive streamed previews and the final answer.

It is a fork of @llblab/[email protected] (SHA afe09c5), repackaged as @evandrodevbr/oh-my-pi-telegram and declared as an omp extension.

Surface	What you can do
Prompt intake	Send text, replies, edits, images, files, albums and voice notes into the session.
Queue control	Messages sent while the agent is busy become queued turns: inspect, delete, promote, continue, abort, stop or force the next one.
Operator menu	/start opens status, prompt templates, model, thinking level, settings, queue and extension sections.
Rich replies	Rich Markdown (default) or legacy Markdown-to-HTML for final answers; optional live draft previews; native ...typing status while the agent works.
Files and voice	Inbound files land in <agent dir>/tmp/telegram (50 MiB default limit); telegram_attach returns artifacts as real files; inbound voice goes through command templates or STT handlers; outbound voice through telegram_voice and TTS providers.
Buttons	Hidden telegram_button comments become inline buttons whose callbacks re-enter the session.
Threaded Mode	One leader plus visible follower omp instances, each with its own Telegram thread, through one bot.
Named profiles	Independent bots from one agent directory, with isolated polling, diagnostics and bus transport.

Why use it

It is a runtime adapter, not a remote terminal. A Telegram prompt is a normal model turn in the session that is active right now and inherits its post-compaction context, so token cost is not proportional only to the new mobile message.

Why this fork and not upstream: @llblab/[email protected] targets the Pi extension platform (@earendil-works/pi-*), and omp consumes the same platform republished as @oh-my-pi/pi-coding-agent. This fork:

1. Renames the package to @evandrodevbr/oh-my-pi-telegram so it is unambiguous in the omp extension registry.
2. Keeps the upstream peerDependencies on @earendil-works/pi-{ai,agent-core,coding-agent} >=0.80.6, with no code changes or shims.
3. Declares the extension through an omp block in package.json (extensions, display name, compatibleWith: >=16.5.2); the old pi block was removed in 572967c.

Do not use it if you need a real terminal from the phone: there are no hidden omp processes, no PTY and no raw TTY input. Telegram can compact the current session but cannot create, resume, fork, browse or switch sessions, and arbitrary slash commands are never forwarded to the TUI. For plain Pi, use upstream @llblab/pi-telegram.

How it works

• The active omp instance owns getUpdates polling for one bot. You start it with /telegram-connect; Telegram never launches hidden omp processes.
• Each Telegram message becomes a turn: it goes to the queue or is dispatched to the active session, then streams back as a preview with the native typing status and ends as a final Rich Markdown reply, optionally with files, voice, buttons or callback actions.
• In Threaded Mode, follower instances talk to the leader over a local bus (Unix socket or named pipe) and get their own Telegram thread.
• Code layout: index.ts is the composition root, lib/*.ts are flat domain modules (queue, polling, locks, bus, menus, rendering, delivery), api/*.ts are the public entry points for companion extensions, and docs/ holds the architecture and contract documents.

Quickstart

Requires omp >= 16.5.2 (package.json → omp.compatibleWith) and Node.js >= 22.19.0 (engines.node).

# From git (this repository)
omp plugin install https://git.evandro.dev.br/evandro/oh-my-pi-telegram.git

# From a local checkout (development)
omp plugin link /path/to/oh-my-pi-telegram

The npm package @evandrodevbr/oh-my-pi-telegram is not published yet. Restart (or reload) omp so the extension loads, then:

1. Create a bot with @BotFather (/newbot) and copy the token.
2. In omp, run /telegram-setup and paste the token.
3. Run /telegram-connect to start polling for this instance.
4. In the bot DM, send /start.

Warning

The first Telegram user to message the bot becomes the allowed owner; everyone else is ignored. Pair right after /telegram-connect, and never put the bot token in chat, source, committed config or logs. Setup can prefill the token from TELEGRAM_BOT_TOKEN, TELEGRAM_BOT_KEY, TELEGRAM_TOKEN or TELEGRAM_KEY.

The saved config is <agent dir>/telegram.json. The agent directory is PI_CODING_AGENT_DIR when set, ~/.omp/agent when the process is omp, and ~/.pi/agent otherwise (lib/paths.ts).

Usage

Commands

In the bot DM:

Command	Purpose
/start	Pair when needed and open the operator menu
/compact	Confirm and run session compaction when safe
/next	Dispatch the next queued turn, aborting first if needed
/continue	Enqueue a priority continuation prompt
/abort	Abort the active run, keeping the queue
/stop	Abort the active run and clear waiting Telegram turns

/help, /status, /model, /thinking, /queue and /settings are hidden shortcuts into the same menus.

Inside omp:

Command	Purpose
/telegram-setup [profile]	Save or update the default (or a named-profile) bot token
/telegram-connect [profile]	Activate a profile and acquire its transport ownership
/telegram-disconnect	Stop polling and release ownership
/telegram-status	Inspect connection, mode, queue, transport and diagnostics

Profile names use lowercase ASCII letters and digits (max 32 characters); default, main and active are reserved.

Environment variables

Area	Variables
Bot token bootstrap	TELEGRAM_BOT_TOKEN, TELEGRAM_BOT_KEY, TELEGRAM_TOKEN, TELEGRAM_KEY
Network family	PI_TELEGRAM_NETWORK_FAMILY = auto, ipv4, ipv6 or ipv4-fallback (default)
Agent data root	PI_CODING_AGENT_DIR
Inbound file limit	PI_TELEGRAM_INBOUND_FILE_MAX_BYTES, TELEGRAM_MAX_FILE_SIZE_BYTES
Outbound attachment limit	PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES, TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES

Defaults: inbound temp files in <agent dir>/tmp/telegram, and assistant: { rendering: "rich", draftPreviews: false }.

Full reference: architecture, public API, delivery, inbound, outbound, voice, multi-instance bus and the rest in the docs index.

Project status

Fork release 0.22.0-evandro.1. Per CHANGELOG.md, the fork re-ran the upstream gates: typecheck, 1,229 of 1,230 tests passing with one platform-only skip, npm audit with 0 vulnerabilities and a clean npm pack --dry-run. CI (.github/workflows/validate.yml) runs npm ci and npm run validate on Ubuntu with Node 24 for every push and pull request.

• A design spec for an omp status-bar segment (docs/superpowers/specs/) needs a new omp core API and is not implemented here.
• In Threaded Mode, threadless messages sent from the All tab are not routed as prompts once bound threads exist; use a bound thread tab.
• release.yml needs a ## <version> heading in CHANGELOG.md; the fork entry sits under ## Unreleased as a ### heading, so a tag fails that check until the section is promoted.
• Open work (promoted-follower reload evidence, native Windows Threaded Mode follow-ups, Telegram client and Rich Markdown quirks) is tracked in BACKLOG.md.

Development:

npm ci
npm run validate   # typecheck + test + audit + pack:check

Engineering conventions are in AGENTS.md.

License

MIT, see LICENSE: copyright Evandro Fonseca Junior (evandrodevbr), llblab and Mario Zechner (badlogic). Built on llblab/pi-telegram, itself a fork of badlogic/pi-telegram; runs inside Oh My Pi and talks to the Telegram Bot API. Unofficial project, not affiliated with Telegram or the Oh My Pi maintainers.

---

_{Made by Evandro Fonseca Junior · git.evandro.dev.br}