llms.txt

# TelegramCode

> Self-hosted Telegram bot that runs OpenCode and Claude Code coding agents on your own machine or VPS, driven from your phone. One forum topic is one project with its own isolated agent session, like terminal tabs.

TelegramCode turns Telegram into a terminal for agentic coding CLIs. It runs on your own machine or server and connects out to Telegram only, so there are no open inbound ports. You bind each forum topic (or the bot's own DM) to a project folder, and each topic runs its own isolated OpenCode or Claude Code session that you drive by chat, voice, or file. Sessions survive both bot restarts and agent-server restarts. It supports voice input (Whisper), photo/file/PDF intake, scheduled prompts, pinned question alerts (a pin pierces a muted topic for exactly one notification), a raw `/terminal` shell, an agent-facing MCP so the agent can send back files/images/video and schedule itself, and 12 UI languages. MIT licensed, Node 22+, install with `npm install -g telegramcode`.

## Project

- [GitHub repository](https://github.com/olosegres/telegramcode): source, issues, and releases (MIT license).
- [README](https://github.com/olosegres/telegramcode#readme): full feature list, quick start, commands, and troubleshooting.
- [npm package](https://www.npmjs.com/package/telegramcode): install with `npm install -g telegramcode` (Node 22+).
- [DEVELOPMENT.md](https://github.com/olosegres/telegramcode/blob/main/DEVELOPMENT.md): architecture and local development.

## Key features

- [Two agent backends](https://github.com/olosegres/telegramcode#features): OpenCode (native server API over HTTP+SSE) and Claude Code (tmux and json-stream backends).
- [One topic per project](https://github.com/olosegres/telegramcode#two-surfaces-group-topics-bot-dm-or-both): forum topics act like terminal tabs, one isolated session each; two topics can share a folder for parallel work.
- [Voice control](https://github.com/olosegres/telegramcode#features): send a voice note, it is transcribed with Whisper and forwarded to the agent.
- [Scheduled and self-driving runs](https://github.com/olosegres/telegramcode#scheduler-schedule): `/schedule` arms cron, one-shot, or N-times jobs per topic, and the agent can schedule itself.
- [Pinned question alerts](https://github.com/olosegres/telegramcode#features): when the agent asks a question the bot pins it, so even a muted topic notifies you once.
- [Raw terminal](https://github.com/olosegres/telegramcode#raw-terminal-terminal): `/terminal` binds a topic to a real shell in the project folder.
- [Restart-safe sessions](https://github.com/olosegres/telegramcode#restart-behaviour): sessions survive both a bot restart and an agent-server restart.
- [Agent-facing MCP tools](https://github.com/olosegres/telegramcode#bot-injected-agent-tools): the agent can send files, images, and video back to you, post multiple messages, and schedule itself.

## Install

- [Quick Start](https://github.com/olosegres/telegramcode#quick-start): `npm install -g telegramcode`, put your bot token in one `.env`, launch from your projects folder, bind a topic.