opencode-telegram-bot

opencode-telegram-bot

OpenCode Telegram bot client for OpenCode CLI: run and monitor AI coding tasks from your phone while everything runs locally on your machine.

Stars: 85

Visit
 screenshot

OpenCode Telegram Bot is a secure Telegram client for OpenCode CLI that allows users to run AI coding tasks, monitor progress, switch models, and manage sessions from their phone. The bot communicates with the local OpenCode server and the Telegram Bot API only, ensuring security. It supports multiple languages and provides features like remote coding, session management, live status updates, model switching, agent modes, voice prompts, context control, input flow control, configurable reply formatting, strict user ID whitelist for security, and UI localization. Users can configure environment variables, voice and audio transcription, model settings, and more. The bot enforces security measures and supports various platforms like macOS, Windows, and Linux.

README:

OpenCode Telegram Bot

npm version CI License: MIT Node.js

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.

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

Quick start: npx @grinev/opencode-telegram-bot

OpenCode Telegram Bot screencast

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 any model from your OpenCode favorites directly in the chat
  • Agent modes — switch between Plan and Build modes on the fly
  • 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
  • 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
  • Configurable reply formatting — assistant replies use Telegram MarkdownV2 by default, with optional raw mode (MESSAGE_FORMAT_MODE=markdown|raw)
  • 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)

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

On first launch, an interactive wizard will guide you through the configuration — it asks for interface language first, then your bot token, user ID, and OpenCode API URL. 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

Platform Status
macOS Fully supported
Windows Fully supported
Linux Experimental — should work, but has not been extensively tested. You may need additional steps such as granting execute permissions.

Bot Commands

Command Description
/status Server health, current project, session, and model info
/new Create a new session
/stop Abort the current task
/sessions Browse and switch between recent sessions
/projects Switch between OpenCode projects
/rename Rename the current session
/opencode_start Start the OpenCode server remotely
/opencode_stop Stop the OpenCode server remotely
/help Show available 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.

Configuration

Localization

  • Supported locales: en, de, es, 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
Variable Description Required Default
TELEGRAM_BOT_TOKEN Bot token from @BotFather Yes
TELEGRAM_ALLOWED_USER_ID Your numeric Telegram user ID Yes
TELEGRAM_PROXY_URL Proxy URL for Telegram API (SOCKS5/HTTP) No
OPENCODE_API_URL OpenCode server URL No http://localhost:4096
OPENCODE_SERVER_USERNAME Server auth username No opencode
OPENCODE_SERVER_PASSWORD Server auth password No
OPENCODE_MODEL_PROVIDER Default model provider Yes opencode
OPENCODE_MODEL_ID Default model ID Yes big-pickle
BOT_LOCALE Bot UI language (supported locale code, e.g. en, de, es, ru, zh) No en
SESSIONS_LIST_LIMIT Max sessions shown in /sessions No 10
PROJECTS_LIST_LIMIT Max projects shown in /projects No 10
SERVICE_MESSAGES_INTERVAL_SEC Service messages interval (thinking + tool calls); keep >=2 to avoid Telegram rate limits, 0 = immediate No 5
HIDE_THINKING_MESSAGES Hide 💭 Thinking... service messages No false
HIDE_TOOL_CALL_MESSAGES Hide tool-call service messages (💻 bash ..., 📖 read ..., etc.) No false
MESSAGE_FORMAT_MODE Assistant reply formatting mode: markdown (Telegram MarkdownV2) or raw No markdown
CODE_FILE_MAX_SIZE_KB Max file size (KB) to send as document No 100
STT_API_URL Whisper-compatible API base URL (enables voice/audio transcription) No
STT_API_KEY API key for your STT provider No
STT_MODEL STT model name passed to /audio/transcriptions No whisper-large-v3-turbo
STT_LANGUAGE Optional language hint (empty = provider auto-detect) No
LOG_LEVEL Log level (debug, info, warn, error) No info

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 bot picks up your favorite models from OpenCode. To add a model to favorites:

  1. Open OpenCode TUI (opencode)
  2. Go to model selection
  3. Hover over the model you want and press Ctrl+F to add it to favorites

These favorites will appear in the model picker opened from the bottom Telegram keyboard.

A free model (opencode/big-pickle) is configured as the default fallback — if you haven't set up any favorites yet, the bot will use it automatically.

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

Script Description
npm run dev Build and start (development)
npm run build Compile TypeScript
npm start Run compiled code
npm run release:notes:preview Preview auto-generated release notes
npm run lint ESLint check (zero warnings policy)
npm run format Format code with Prettier
npm test Run tests (Vitest)
npm run test:coverage Tests with coverage report

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

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.

License

MIT © Ruslan Grinev

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for opencode-telegram-bot

Similar Open Source Tools

For similar tasks

For similar jobs