This project provides a secure, local Telegram client for the OpenCode CLI, enabling users to run and monitor AI coding tasks directly from their mobile phones. It targets OpenCode users seeking a convenient and private way to manage AI development workflows without exposing APIs or opening network ports, acting as a lightweight alternative to OpenClaw.

How It Works

The OpenCode Telegram Bot operates as a local Node.js application that interfaces with both the OpenCode CLI server (defaulting to http://localhost:4096) and the Telegram Bot API. It prioritizes security by maintaining a strict user ID whitelist and communicating only locally, ensuring no external attack surface beyond the Telegram API itself. This design allows for remote control and monitoring of AI coding tasks while keeping all processing and data on the user's machine.

Quick Start & Requirements

• Primary install/run: Execute npx @grinev/opencode-telegram-bot. Alternatively, install globally via npm install -g @grinev/opencode-telegram-bot and run with opencode-telegram start. Cloning the repository and running npm run dev is for development.
• Prerequisites: Node.js 20+, OpenCode CLI installed and running (opencode serve), a Telegram Bot token from @BotFather, and your Telegram User ID from @userinfobot. Optional: Whisper-compatible API details (STT_API_URL, STT_API_KEY) for voice prompt transcription.
• Setup: An interactive wizard guides initial configuration, including language, bot token, user ID, and OpenCode API URL.
• Links: GitHub repository for development: https://github.com/grinev/opencode-telegram-bot.

Highlighted Details

• Remote Operations: Send prompts, manage sessions, switch models, and execute OpenCode custom commands from Telegram.
• Real-time Monitoring: A pinned Telegram message provides live updates on project status, model usage, and file changes.
• Advanced Features: Supports voice prompts (via STT API), file attachments (code, logs, configs), and interactive Q&A/permission approvals through inline buttons.
• Scheduled Tasks: Allows scheduling prompts for later execution or recurring intervals (minimum 5 minutes), with support for up to 10 tasks by default.
• Security: Employs a strict user ID whitelist, ensuring only authorized users can interact with the bot.
• Localization: Offers UI support for multiple languages, including English, German, Spanish, French, Russian, and Simplified Chinese.

Maintenance & Community

The project is maintained by Ruslan Grinev. Community interaction and feature discussions are hosted on GitHub Discussions.

Licensing & Compatibility

The project is released under the MIT license, which permits commercial use and integration with closed-source projects.

Limitations & Caveats

The bot requires a locally running OpenCode server instance. Scheduled tasks execute outside the active chat session and are limited to the build agent. Development requires manual restarts after code modifications, as auto-restart functionality is not implemented to maintain persistent connections. Voice transcription requires separate STT API configuration.