OpenCode Telegram Bot: Run AI Coding Tasks From Your Phone Without Opening Ports
OpenCode mobile client via Telegram: run and monitor AI coding tasks from your phone while everything runs locally on your machine. Scheduled tasks support.
At a glance
- What is it?
- A Telegram client for the OpenCode CLI that keeps all execution local while letting you prompt, monitor, and manage sessions remotely. It solves the mobile access problem for OpenCode users, with scheduled tasks and a strict user whitelist.
- Who is it for?
- Adopt this bot if you already use OpenCode and want to issue prompts, monitor sessions, and switch models from a phone without exposing your machine to the internet. Skip it if you need multi-user collaboration, a web interface, or if you cannot run Node.js 22.14+ and an OpenCode server on the same host.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 14, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem: OpenCode Is Stuck at Your Desk
The bot is not a cloud service. It is a bridge between two local endpoints: your OpenCode server and the Telegram Bot API. Because both connections are outbound from your machine, you do not need to configure port forwarding or a public IP. That is a meaningful security property for developers who would otherwise consider SSH-ing into their home machine from a phone.
How It Communicates: Local Server, Outbound-Only
The bot also includes a message queue feature, enabled via `/settings`, that holds messages while the agent is busy and sends them one by one afterwards. This is a practical solution to a common problem: you send a prompt, the agent starts working, and you want to send a follow-up without breaking the flow. The queue prevents accidental interleaving and keeps context consistent.
Getting It Running: npx, Global Install, and Docker
A notable caveat: if you run the npx command from the repository root, it may fail with `opencode-telegram: not found`. The README says to use the Development section for source runs, which is not included in the truncated material. So stick to the npm package unless you are a contributor.
Scheduled Tasks and the OpenClaw Comparison
One of the headline features is scheduled tasks. The bot can run prompts later or on a recurring interval. The README calls this 'a lightweight OpenClaw alternative for OpenCode users.' OpenClaw is a separate project that provides autonomous agent capabilities, and this bot positions itself as a simpler version for those who already use OpenCode. That is a useful comparison: OpenClaw is a full agent framework, while this bot is a thin scheduling layer on top of OpenCode's existing CLI. If you need complex multi-step autonomous workflows, this bot is not that. But if you just want to say 'run this prompt every morning at 9am' or 'run this after I leave the office,' it fits. The scheduled tasks feature is not documented in detail in the visible README, so you would need to check the source or the full docs for exact syntax and storage. That is a gap in the documentation that could hurt adoption.
Security Model: Whitelist, Not Encryption
The bot's security model is simple: a strict user ID whitelist. The README says 'no one else can access your bot, even if they find it.' That means the bot only responds to messages from your Telegram user ID. It does not mention end-to-end encryption or TLS beyond what Telegram provides. The bot token itself is a secret, and the OpenCode server credentials are optional. If you run the bot on a machine with multiple users, you need to ensure the `.env` file is protected. The security model is adequate for a solo developer, but it is not a multi-user system. If you want to share access with a team, you would need to modify the whitelist logic, which is not documented. Also, because the bot controls a local coding agent, anyone who compromises your Telegram account or your machine could trigger arbitrary code execution. That is inherent to the design, and the README does not downplay it.
Limitations and Wrong Tool Cases
The most obvious limitation is that the bot is tied to Telegram. If you do not use Telegram, or if your organization blocks it, this bot is useless. There is no web interface, no Slack integration, no mobile app other than Telegram. The README also notes that the latest npm release may not include every feature described in the README, which tracks the `main` branch. That means you might read about a feature, install the package, and find it missing. That is a real version-skew problem. Another limitation is that the bot requires OpenCode to be running on the same machine. If you want to control a remote machine, you would need to run the bot there, not on your local machine. The bot does not manage the OpenCode server lifecycle beyond the `/opencode_start` and `/opencode_stop` commands, and those only work if the bot is already running. Finally, the bot is not an autonomous agent. It depends on OpenCode's own agent capabilities. If OpenCode itself cannot handle a task, the bot will not help. For complex multi-step automations, you would be better off with a dedicated agent framework like OpenClaw, which the README itself references.
Alternatives: OpenClaw and Raw SSH
The README names OpenClaw as the main alternative. OpenClaw is a general-purpose autonomous agent that can run coding tasks, schedule them, and interact with multiple platforms. The difference in approach is that OpenClaw is a standalone agent framework, while this bot is a thin client for an existing CLI. OpenClaw would give you more flexibility in defining workflows and integrating with other tools, but it is heavier and may require more setup. Another alternative is to simply SSH into your machine from your phone and run OpenCode in a terminal emulator. That gives you full control but requires opening an SSH port, which this bot explicitly avoids. So the trade-off is: use this bot for a secure, chat-based interface with no network exposure, or use OpenClaw for a more powerful but more complex agent, or use SSH for full terminal access at the cost of security. The bot's niche is the middle ground: simple, secure, and mobile-friendly.
Maintenance and License
The project is MIT licensed, which means you can use it freely, modify it, and embed it in commercial products without paying fees. The repository is actively maintained, with recent releases in August 2026 and a CI workflow badge. The maintenance cost is moderate: you need to keep the npm package updated to get new features and bug fixes, and you need to track OpenCode's API changes, since the bot depends on the local server. The README warns about version skew, so you should check the changelog before upgrading. There is no dedicated documentation site; the README is the primary source, and it references separate docs like `docs/LINUX_SYSTEMD_SETUP.md` and a `PRODUCT.md` for the task list. That suggests the project is well organized but still a solo effort. For a production setup, you would want to set up systemd or Docker to keep the bot running, and the README provides guidance for systemd. The bot itself is a Node.js application, so you need to monitor its memory and log output. There is no mention of built-in logging or metrics, so you would rely on the process manager.
Editorial conclusion
Adopt this bot if you already use OpenCode and want to issue prompts, monitor sessions, and switch models from a phone without exposing your machine to the internet. Skip it if you need multi-user collaboration, a web interface, or if you cannot run Node.js 22.14+ and an OpenCode server on the same host. Before adopting, verify that your OpenCode version supports the API endpoints the bot expects, especially for live session tracking and background notifications, and test the scheduled tasks feature in a staging environment. The bot ties you to Telegram as the only control surface, so confirm that fits your workflow. If you need a different chat platform or a full agent framework, look elsewhere.
Community notes