TelePi CLI
A Telegram bridge for the Pi coding agent: continue sessions from your phone and hand them back to the terminal
- 146 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- A Telegram chat gains control of a coding agent on your computer: a leaked bot token or a mistake in the allowlist gives strangers access to your repositories.
- Cloud transcription sends voice to OpenAI (or to your own recognition URL), and the bot token and keys sit in `~/.config/telepi/config.env`.
Install
- Services
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/telepiDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- A Telegram chat gains control of a coding agent on your computer: a leaked bot token or a mistake in the allowlist gives strangers access to your repositories.
- Cloud transcription sends voice to OpenAI (or to your own recognition URL), and the bot token and keys sit in `~/.config/telepi/config.env`.
This is third-party code. Review the repository files before installing.
What it does
TelePi is a Telegram bot that runs on your own machine and connects a chat to the Pi coding agent (the pi-mono project). It opens real Pi sessions in your repositories. In the terminal you run `/handoff`, in Telegram you continue the session with text, voice or a photo, and `/handback` returns the same session to the terminal and copies the resume command to the clipboard. Each chat or forum topic gets its own session, retry history and picker state. Bot commands: `/sessions` lists sessions across all projects with tap-to-switch buttons, `/model` changes the model, `/tree`, `/branch` and `/label` navigate the session tree, `/retry` repeats the last prompt and `/abort` cancels the operation. Through `/commands` Telegram reaches Pi prompt templates, skills and extension commands. Voice messages are transcribed by Parakeet CoreML on Apple Silicon, Sherpa-ONNX on Intel Macs and CPUs, or OpenAI Whisper in the cloud. Photos and image documents go to Pi as image inputs. For scheduled jobs there is a prompt inbox: cron, a mail filter or a webhook drops a `.txt` file into a directory and TelePi sends its contents to the chat.
Who it is for. Developers who already work with Pi and want to answer the agent from a phone: on the road, away from the desk, by voice or with a screenshot of an error.
Good fit when
- The agent waits for an answer while you are away from the computer: a Telegram message continues the session.
- An error is easier to show with a screenshot than to describe, and the photo goes to Pi as an image.
- Dictating beats typing on a phone, and transcription should run locally.
- External events (cron, a webhook, a mail filter) should trigger agent prompts through the inbox directory.
- Several projects run in different forum topics and each topic must keep its own session.
Not a fit when
- You do not use the Pi agent: TelePi only drives Pi.
- A public bot for other people is needed: access is limited to your Telegram user IDs.
- The work machine is off or asleep: the bot runs on it, not in the cloud.
Example request
Send the bot a voice message: "Run the tests in the project and tell me which ones failed." The bot transcribes it and passes the text to the Pi session.Limitations
You need Node.js 22.19 or newer, a bot token from @BotFather, your numeric Telegram ID for the allowlist and a working Pi (the `~/.pi/agent/auth.json` file). The service is installed as `launchd` on macOS and `systemd --user` on Linux; the README says nothing about a Windows service. Local transcription needs `ffmpeg` plus `parakeet-coreml` or `sherpa-onnx-node` with a model in `SHERPA_ONNX_MODEL_DIR`, cloud transcription needs `OPENAI_API_KEY` or your own recognition URL. This is an early open-source release.
How to disable. Stop the service (`launchctl` on macOS, `systemctl --user disable --now telepi.service` on Linux), remove the package with `npm uninstall -g @futurelab-studio/telepi` and the `~/.pi/agent/extensions/telepi-handoff.ts` extension; the configuration lives in `~/.config/telepi/config.env`.
FAQ
How do I install TelePi?
Run `npm install -g @futurelab-studio/telepi`, then `telepi setup` asks for the bot token, allowlisted IDs and workspace, installs the service and the `/handoff` extension for Pi. `telepi status` shows the state.
How do I move a session to Telegram and back?
Run `/handoff` in Pi, open your bot and write. To return, send the bot `/handback`: the same session resumes in the terminal with the command copied to the clipboard.
Who can message the bot?
Only users from `TELEGRAM_ALLOWED_USER_IDS`. Everyone else is rejected even if they find the bot name. Pi tools are scoped to the active session's workspace.
Does voice transcription work offline?
Yes, through local Parakeet CoreML (Apple Silicon) or Sherpa-ONNX (Intel Mac, CPU) if `ffmpeg` and the required packages are installed. The cloud option uses OpenAI Whisper.
Can TelePi run in Docker?
Yes. For stricter filesystem isolation there is a non-root image with explicit read and write mounts.
Discussion
No questions or reviews yet.
Related
All Telegram toolsA Telethon MCP server: the agent reads and sends messages and manages chats, contacts and folders in your Telegram account
A Telegram bot for OpenCode: send coding tasks, watch progress and switch models from your phone while OpenCode keeps running on your own computer
Connects Claude Code, Cursor, Codex or OpenCode to Telegram, Slack and Discord: teammates message a bot, an agent replies
Telegram MCP by chaindead
Telegram MCP
A Go MCP server for your Telegram account: the agent reads dialogs and unread messages, marks them read, leaves replies as drafts
Claude-to-IM
claude-to-im
A bridge between Claude Code or Codex and messengers: talk to the agent from Telegram, Discord, Feishu, QQ or WeChat
Telegram API MCP
telegram-api-mcp
MCP server for the Telegram Bot API: messages, channels, forums, payments and long posts from a bot, with Telegram rate limits built in
README in short
The README opens with a five-minute start and a first session, then covers the security model and the full feature list. Manual setup, troubleshooting of common failures, a table of bot commands and sections on the prompt inbox, voice and images follow.