OpenCode Telegram Bot
Control OpenCode coding agents from anywhere via Telegram, while everything runs locally on your machine.
- Source repo
- grinev/opencode-telegram-bot
- Stars
- ★ 1.3k
- Last updated
- 1d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 64/100 · Some gaps
At a glance
- How it runs
- Works with
- Platform-specific
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Developers who want to submit coding tasks to a local OpenCode instance from their phone while away from their desk.
- Not a fit if
- Teams not using the OpenCode CLI
- Users who cannot run a local OpenCode server on a fixed port
- Source review
- 64/100 · Some gaps
What does this agent do, and when should you use it?
OpenCode Telegram Bot is a secure Telegram client for the OpenCode CLI that runs on your local machine. It communicates with your local OpenCode server (default http://localhost:4096) and the Telegram Bot API, without exposing any open ports. You can create and manage sessions, switch models, toggle Plan/Build modes, watch subagent progress, run custom commands and skills, manage git worktrees, and browse files. The bot also supports scheduled tasks, turning it into a lightweight OpenClaw alternative for OpenCode users. It enforces strict user ID whitelisting for security and is localized into multiple languages including English, Arabic, German, Spanish, French, Italian, Portuguese, Russian, and Simplified Chinese.
The bot connects to a local OpenCode server (opencode serve) and the Telegram Bot API. Users send prompts via Telegram messages, which are forwarded to the OpenCode agent; results, including code files, are sent back. It supports session creation (/new), session switching (/sessions), server and model status (/status), model switching via favorites/recent history, agent mode switching (Plan/Build), custom commands (/commands), skills (/skills), git worktree switching (/worktree), file browsing (/ls), and scheduled tasks (/task). It also integrates voice input (via Whisper-compatible STT), file attachments (images, PDFs, text), a message queue, and context compaction.
- Developers who want to submit coding tasks to a local OpenCode instance from their phone while away from their desk.
- Users who need to schedule periodic code maintenance or review tasks to run automatically at set times.
- Teams that want to monitor multiple OpenCode sessions in real time and receive background notifications from Telegram.
- Power users who need to quickly switch between models or agent modes without opening the TUI locally.
- Mobile users who prefer voice input for capturing coding ideas and receiving spoken replies via TTS.
- Developers managing multiple git worktrees and need to switch between them remotely via Telegram.
How do you install or deploy this agent?
- Create a Telegram bot via @BotFather and obtain the bot token. 2. Get your numeric user ID from @userinfobot. 3. Install Node.js 22.14+ and OpenCode CLI on your machine. 4. Start the OpenCode server with
opencode serve. 5. Run the bot withnpx @grinev/opencode-telegram-bot@latest. 6. On first run, an interactive wizard will guide you through setting the interface language, bot token, user ID, and OpenCode API URL.
How do you use this agent?
After installation, open the bot in Telegram and send any text message as a coding prompt. Use /help to see all commands, /status to check server and session health. To track live sessions, start OpenCode with a fixed port: opencode --port 4096 or opencode serve --port 4096. For scheduled tasks, use /task to create and /tasklist to manage them. Adjust runtime settings like message queue or audio replies via /settings.
What are this agent's strengths and limitations?
- No open ports or exposed APIs; all communication is outbound to Telegram, enhancing security in home or work networks.
- Scheduled task support makes it a viable lightweight alternative to OpenClaw for OpenCode automation.
- Comprehensive remote control: session management, model switching, custom commands, skills, worktree switching, and file browsing.
- Voice input and TTS output, enabling hands-free interaction from mobile devices.
- Tightly coupled to the OpenCode ecosystem; only works with OpenCode CLI and cannot be used with other coding agents.
- Requires manual setup of a local OpenCode server with a fixed port (default 4096), which may conflict with other services.
- Scheduled tasks always run with the
buildagent, limiting flexibility for tasks needingplanmode or other agents. - Voice transcription depends on an external Whisper-compatible API, requiring additional API keys and configuration.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| OpenCode Telegram Bot This agent | 64 · Some gaps | CLIFree + model costs | ★ 1.3k | 1d ago | TypeScript | — |
| Ivy Tendril | 56 · Major gaps | Desktop appFree + model costs | ★ 203 | 1mo ago | C# | Codex · Claude Code |
| NeuroSquad Terminal Dashboard | 76 · Good | CLIFree + model costs | ★ 53 | 5d ago | TypeScript | Codex · Claude Code |
| CC-Connect | 60 · Some gaps | CLIFree + model costs | ★ 16k | 3d ago | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: user ID whitelist restricts access, commands require confirmation (e.g., custom commands), data flow transparent (only communicates with local OpenCode and Telegram API), sensitive data (tokens, passwords) managed via environment variables with warnings, dependencies have fixed versions but no security audit, external effects limited to local server and Telegram, rollback supported (/messages revert), source attribution clear (MIT license and author). Deductions: dependency security lacks vulnerability scanning or audit evidence, external effects not explicitly limited in network scope.
Evidence shows: consistent code structure, tests cover formatting functions, dependency versions fixed, error messages documented (e.g., timeout marked as failed). Deductions: no runtime error handling details, dependency availability not verified.
Evidence shows: targets developers, supports multiple platforms and scenarios (remote coding, scheduled tasks), capability boundaries clear (command list), trigger precision (prompts sent only when no blocking interaction), environment fit good (Node version, system support). Deductions: no detailed environment configuration examples.
Evidence shows: clear information architecture (README, docs, tests), detailed install instructions (npx, global install), stable naming (commands and variables), examples and FAQ (README), known limitations partially mentioned (e.g., scheduled task limits), MIT license, version and changelog present (package.json version, publish workflow), maintenance responsibility clear (author and community). Deductions: known limitations incomplete, changelog not directly provided.
Evidence shows: output usable (code sent as files), high marginal value (remote monitoring, scheduled tasks), cost-benefit reasonable (free open source). Deductions: no performance or resource consumption data.
Evidence shows: README feature descriptions align with code and tests, tests cover some features, facts and inferences separated (README distinguishes planned features). Deductions: cross-source verification insufficient, relies only on single repository.
- Dependency security lacks vulnerability scanning or audit evidence; check dependency versions and known vulnerabilities.
- External effects scope not explicitly limited to network; ensure local OpenCode server listens only on localhost.
- Known limitations section incomplete; refer to full documentation.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Changes - Named nested launches — when a subagent launches another one, its card's activity line now says which task it started, as in 🤖 Running Task: Count Kotlin files, and compact mode names the launched task the same way. - Shorter execute lines — long code in OpenCode V2 Code Mode execute calls is cut in the chat the same way long bash commands are, so a big script no longer floods the conversation. …View on GitHub ↗ -
Release notes excerpt
Changes - Prebuilt Docker images — stable releases are now published as multi-arch (linux/amd64, linux/arm64) images on ghcr.io/grinev/opencode-telegram-bot, so you can pull the bot instead of building it locally. ([@mitchellhuang](https://github.com/mitchellhuang)) - Docker health check — the Docker image now reports the container as unhealthy when the bot stops responding, through a loopback-only health endpoint that also tells whether OpenCode is reachable. ([@iagorobo24-hub](https://github.com/iagorobo24-hub)) Fixes …View on GitHub ↗ -
Release notes excerpt
Fixes - No live polls for questions that already ended — a poll delayed by Telegram rate limits no longer appears with live buttons after its question was cancelled or answered elsewhere, and an answer that fails to reach OpenCode keeps the poll answerable with a visible outcome instead of being silently lost. - Queue buttons clear after a reconnect on OpenCode V2 — messages the agent has already picked up no longer keep their ❌ queue buttons on the reply keyboard after OpenCode's event stream reconnects. …View on GitHub ↗