grinev/opencode-telegram-bot: OpenCode mobile client via Telegram: run and monitor AI coding tasks from your phone while everything runs locally on your machine. Scheduled tasks support. Can be used as lightweight OpenClaw alternative.

OpenCode Telegram Bot

OpenCode Telegram Bot is a secure Telegram client for OpenCode CLI that runs on your local machine.

Run AI coding tasks, monitor progress, switch models, and manage sessions from your phone.

No open ports, no exposed APIs. The bot communicates with your local OpenCode server and the Telegram Bot API only.

Scheduled tasks support. Turns the bot into a lightweight OpenClaw alternative for OpenCode users.

Platforms: macOS, Windows, Linux

Languages: English (en), Deutsch (de), Español (es), Français (fr), Русский (ru), 简体中文 (zh)

Features

• Remote coding — send prompts to OpenCode from anywhere, receive complete results with code sent as files
• Session management — create new sessions or continue existing ones, just like in the TUI
• Live status — pinned message with current project, model, context usage, and changed files list, updated in real time
• Model switching — pick models from OpenCode favorites and recent history directly in the chat (favorites are shown first)
• Agent modes — switch between Plan and Build modes on the fly
• Custom Commands — run OpenCode custom commands (and built-ins like init / review) from an inline menu with confirmation
• Interactive Q&A — answer agent questions and approve permissions via inline buttons
• Voice prompts — send voice/audio messages, transcribe them via a Whisper-compatible API, then forward recognized text to OpenCode
• File attachments — send images, PDF documents, and any text-based files to OpenCode (code, logs, configs etc.)
• Scheduled tasks — schedule prompts to run later or on a recurring interval; see Scheduled Tasks
• Context control — compact context when it gets too large, right from the chat
• Input flow control — when an interactive flow is active, the bot accepts only relevant input to keep context consistent and avoid accidental actions
• Security — strict user ID whitelist; no one else can access your bot, even if they find it
• Localization — UI localization is supported for multiple languages (BOT_LOCALE)

Planned features currently in development are listed in Current Task List.

Prerequisites

• Node.js 20+ — download
• OpenCode — install from opencode.ai or GitHub
• Telegram Bot — you’ll create one during setup (takes 1 minute)

Quick Start

1. Create a Telegram Bot

1. Open @BotFather in Telegram and send /newbot
2. Follow the prompts to choose a name and username
3. Copy the bot token you receive (e.g. 123456:ABC-DEF1234...)

You’ll also need your Telegram User ID — send any message to @userinfobot and it will reply with your numeric ID.

2. Start OpenCode Server

Start the OpenCode server:

opencode serve

The bot connects to the OpenCode API at http://localhost:4096 by default.

3. Install & Run

The fastest way — run directly with npx:

npx @grinev/opencode-telegram-bot

Quick start is for npm usage. You do not need to clone this repository. If you run this command from the source directory (repository root), it may fail with opencode-telegram: not found. To run from sources, use the Development section.

On first launch, an interactive wizard will guide you through the configuration — it asks for interface language first, then your bot token, user ID, OpenCode API URL, and optional OpenCode server credentials (username/password). After that, you’re ready to go. Open your bot in Telegram and start sending tasks.

Alternative: Global Install

npm install -g @grinev/opencode-telegram-bot
opencode-telegram start

To reconfigure at any time:

opencode-telegram config

Supported Platforms

Bot Commands

Any regular text message is sent as a prompt to the coding agent only when no blocking interaction is active. Voice/audio messages are transcribed and then sent as prompts when STT is configured.

/opencode_start and /opencode_stop are intended as emergency commands — for example, if you need to restart a stuck server while away from your computer. Under normal usage, start opencode serve yourself before launching the bot.

Scheduled Tasks

Scheduled tasks let you prepare prompts in advance and run them automatically later or on a recurring schedule. This is useful for periodic checks, routine code maintenance, or tasks you want OpenCode to execute while you are away from your computer. Use /task to create a scheduled task and /tasklist to review or delete existing ones.

• Each task is created from the currently selected OpenCode project and model
• Scheduled executions currently always run with the build agent
• Tasks run outside your active chat session, so they do not interrupt or affect the current session flow
• The minimum recurring interval is 5 minutes
• Up to 10 scheduled tasks can exist at once by default; change this with TASK_LIMIT in your .env

Configuration

Localization

• Supported locales: en, de, es, fr, ru, zh
• The setup wizard asks for language first
• You can change locale later with BOT_LOCALE

Environment Variables

When installed via npm, the configuration wizard handles the initial setup. The .env file is stored in your platform’s app data directory:

• macOS: ~/Library/Application Support/opencode-telegram-bot/.env
• Windows: %APPDATA%\opencode-telegram-bot\.env
• Linux: ~/.config/opencode-telegram-bot/.env

Keep your .env file private. It contains your bot token. Never commit it to version control.

Voice and Audio Transcription (Optional)

If STT_API_URL and STT_API_KEY are set, the bot will:

1. Accept voice and audio Telegram messages
2. Transcribe them via POST {STT_API_URL}/audio/transcriptions
3. Show recognized text in chat
4. Send the recognized text to OpenCode as a normal prompt

Supported provider examples (Whisper-compatible):

• OpenAI
  • STT_API_URL=https://api.openai.com/v1
    • STT_MODEL=whisper-1
• Groq
  • STT_API_URL=https://api.groq.com/openai/v1
    • STT_MODEL=whisper-large-v3-turbo
• Together
  • STT_API_URL=https://api.together.xyz/v1
    • STT_MODEL=openai/whisper-large-v3

If STT variables are not set, voice/audio transcription is disabled and the bot will ask you to configure STT.

Model Configuration

The model picker uses OpenCode local model state (favorite + recent):

• Favorites are shown first, then recent
• Models already in favorites are not duplicated in recent
• Current model is marked with ✅
• Default model from OPENCODE_MODEL_PROVIDER + OPENCODE_MODEL_ID is always included in favorites

To add a model to favorites, open OpenCode TUI (opencode), go to model selection, and press Cmd+F/Ctrl+F on the model.

Security

The bot enforces a strict user ID whitelist. Only the Telegram user whose numeric ID matches TELEGRAM_ALLOWED_USER_ID can interact with the bot. Messages from any other user are silently ignored and logged as unauthorized access attempts.

Since the bot runs locally on your machine and connects to your local OpenCode server, there is no external attack surface beyond the Telegram Bot API itself.

Development

Running from Source

git clone https://github.com/grinev/opencode-telegram-bot.git
cd opencode-telegram-bot
npm install
cp .env.example .env
# Edit .env with your bot token, user ID, and model settings

Build and run:

npm run dev

Available Scripts

Note: No file watcher or auto-restart is used. The bot maintains persistent SSE and long-polling connections — automatic restarts would break them mid-task. After making changes, restart manually with npm run dev.

Troubleshooting

Bot doesn’t respond to messages

• Make sure TELEGRAM_ALLOWED_USER_ID matches your actual Telegram user ID (check with @userinfobot)
• Verify the bot token is correct

“OpenCode server is not available”

• Ensure opencode serve is running in your project directory
• Check that OPENCODE_API_URL points to the correct address (default: http://localhost:4096)

No models in model picker

• Add models to your OpenCode favorites: open OpenCode TUI, go to model selection, press Ctrl+F on desired models
• Verify OPENCODE_MODEL_PROVIDER and OPENCODE_MODEL_ID point to an available model in your setup

Linux: permission denied errors

• Make sure the CLI binary has execute permission: chmod +x $(which opencode-telegram)
• Check that the config directory is writable: ~/.config/opencode-telegram-bot/

Contributing

Please follow commit and release note conventions in CONTRIBUTING.md.

Community

Have questions, want to share your experience using the bot, or have an idea for a feature? Join the conversation in GitHub Discussions.

License

MIT © Ruslan Grinev