OpenCode Telegram Bot
Control OpenCode coding agents from anywhere via Telegram, while everything runs locally on your machine.
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.
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.
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 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.