OpenCode Telegram Bot CLI
A Telegram bot for OpenCode: send coding tasks, watch progress and switch models from your phone while OpenCode keeps running on your own computer
- 1,297 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Prompts sent through the Telegram chat reach an agent that edits files and runs commands on your computer
- The bot token and user ID sit in a .env file, and local JSON commands run in a shell with the bot's permissions
- Project files can be downloaded from the chat with /ls, and attachments go to the agent and the speech-to-text service
Install
- Works in
- Services
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/opencode-telegram-botDetects 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.
- Prompts sent through the Telegram chat reach an agent that edits files and runs commands on your computer
- The bot token and user ID sit in a .env file, and local JSON commands run in a shell with the bot's permissions
- Project files can be downloaded from the chat with /ls, and attachments go to the agent and the speech-to-text service
This is third-party code. Review the repository files before installing.
What it does
The bot connects to a local OpenCode server and exposes its features in a Telegram chat. It starts with npx @grinev/opencode-telegram-bot@latest. With no settings in place, a wizard asks for the language, a bot token from @BotFather, your numeric user ID, the OpenCode version and its API address. The bot has no open ports and no external APIs: it talks only to the local OpenCode server and the Telegram Bot API. In the chat you send a prompt and get the result, with code delivered as files. /new, /sessions, /recent and /messages manage sessions, including revert and fork from an earlier message. A pinned message shows the project, model, context usage and changed files. The bot switches between Plan and Build modes and favorite models, runs OpenCode custom commands and skills, and takes answers to agent questions and permissions through buttons. It also accepts voice messages through a Whisper-compatible API, images, PDFs and text files, browses project files with /ls and runs scheduled tasks with an interval of 5 minutes or more. It works with classic OpenCode V1 and the new V2.
Who it is for. For people who run OpenCode on their own computer and want to give it tasks and answer its questions from a phone through Telegram.
Good fit when
- A long job runs on your home computer, you are away and want to see progress and answer a permission request
- You want to schedule a recurring prompt, such as a project check every hour, and get the result in the chat
- You dictate a task by voice and the bot transcribes it through a Whisper-compatible API
- You need to switch the model or Plan and Build mode in a running session without reaching a terminal
- You want to follow a session you started in console OpenCode and continue it from the chat
Not a fit when
- Your agent is Claude Code or Codex: the bot controls only an OpenCode server
- The computer with OpenCode is off or asleep: the bot runs on the same machine and does nothing without it
- You cannot keep a Telegram bot token and a user ID on the work machine
- You need access for several people: the bot allows only one whitelisted user
Example request
Run the project tests and, if they fail, fix the cause and send me the list of changed filesLimitations
- Needs Node.js 22.14 or newer and an installed OpenCode with a running server, usually via opencode serve.
- The server version is set with the OPENCODE_SERVER_VERSION variable; the bot does not detect it. Sessions are not shared between V1 and V2.
- V2 requires a server password; for V1 it is optional.
- The bot token and user ID are kept in a .env file on your machine.
- Local JSON commands in the local-commands folder run in a shell with the bot's permissions, so trust those files as code.
- The project notes that its page tracks the main branch and may describe features not yet released.
How to disable. Stop the bot with opencode-telegram stop if you ran it in the background, or end the process. Remove the package with npm uninstall -g @grinev/opencode-telegram-bot. Revoke the bot token with @BotFather and delete the .env settings file by hand.
FAQ
How do I set up a Telegram bot for OpenCode?
Create a bot with @BotFather and copy the token, get your numeric ID from @userinfobot, start opencode serve and run npx @grinev/opencode-telegram-bot@latest. The wizard asks for the remaining values.
Does the bot work with OpenCode V2?
Yes. Set OPENCODE_SERVER_VERSION=v2; the default is v1. V2 listens on http://127.0.0.1:49374 by default and requires the server password, which opencode service get password returns.
How do I continue a terminal session from Telegram?
The bot tracks the selected session. With V2 this works out of the box; with V1 you start console OpenCode on the same port, for example opencode --port 4096, and pick the same session in the bot.
Who else can message my bot?
Nobody. Access is by whitelist: the bot answers only the user whose ID is in TELEGRAM_ALLOWED_USER_ID, even if someone else finds the bot.
Can I run tasks on a schedule?
Yes, with /task. The minimum recurring interval is 5 minutes, up to 10 tasks exist by default and one run waits up to 120 minutes. TASK_LIMIT and SCHEDULED_TASK_EXECUTION_TIMEOUT_MINUTES change those limits.
Discussion
No questions or reviews yet.
Related
All Telegram toolsConnects Claude Code, Cursor, Codex or OpenCode to Telegram, Slack and Discord: teammates message a bot, an agent replies
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
Self-hosted monitoring and remote approvals for Claude Code and Codex via Telegram, Feishu or a web terminal
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
Content Factory for five platforms
Content Factory
An OpenCode skill with four subagents: turns a lesson topic into a post for Telegram, VK, Dzen, a blog and LinkedIn with a cover image
A skill and CLI for exporting and fuzzy-searching Telegram chat history: local database, vector search, read-only
Comparison with similar tools
Entries that share the main search query, and how they differ.
README in short
The project page presents the bot as a secure Telegram client for OpenCode that runs on your machine with no open ports. It continues with a feature list, requirements and three launch steps: create a bot, start the OpenCode server, run npx. Then come the global install, background mode, a command table, session revert and fork, scheduled tasks, live session tracking, the V1 and V2 difference and a table of environment variables. The bot is translated into 12 languages, Russian among them.