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), العربية (ar), Deutsch (de), Español (es), Français (fr), Italiano (it), 한국어 (ko), Português (Brasil) (pt), Русский (ru), 简体中文 (zh)

I use boardown, my open-source Markdown-based task board, to plan and track this project. It stores tasks in plain .md files and can be used as a VS Code extension or a desktop app.

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
• Track live session — follow a live OpenCode CLI session; see Track Existing Session
• Background session notifications — get short notifications when detached or non-current sessions in the current project/worktree reply, ask questions, or request permissions
• Live status — pinned message with current project/worktree, 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), or browse all models by provider
• Agent modes — switch between Plan and Build modes on the fly
• Subagent activity — watch live subagent progress in chat, including the current task, agent, model, and active tool step
• Custom Commands — run OpenCode custom commands (and built-ins like init/review) from an inline menu with confirmation
• Skills Catalog — browse OpenCode skills from an inline menu and run them immediately or with arguments in the next message
• Interactive Q&A — answer agent questions and approve permissions via inline buttons
• Runtime settings — use /settings to change runtime preferences; see Runtime Settings
• Voice prompts — send voice/audio messages, transcribe them via a Whisper-compatible API, and optionally enable spoken replies in /settings
• File attachments — send images, PDF documents, and text-based files to OpenCode, including multiple files in one Telegram album
• Scheduled tasks — schedule prompts to run later or on a recurring interval; see Scheduled Tasks
• Message queue — enable in /settings to hold messages sent while the agent is busy, send them one by one afterwards, and manage them from the bottom keyboard
• 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
• Git worktree switching — browse and switch between existing git worktrees for the current repository with /worktree
• 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)
• Docker support — run the bot as a container while OpenCode stays on the host; see Docker Deployment
• Interactive file browser — use /ls to browse files and directories inside the current project, open subdirectories, go back, and download files by tapping them
• Attach a file to your next prompt — tap 📎 Attach to next prompt on a text file in /ls, and it is sent to OpenCode together with your next message, once

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

Prerequisites

• Node.js 22.14+ — 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

Run the OpenCode server on the same machine where the bot runs:

opencode serve

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

After the bot is configured, you can also start and stop the local OpenCode server from Telegram with /opencode_start and /opencode_stop.

3. Install & Run

The fastest way — run directly with npx:

npx @grinev/opencode-telegram-bot@latest

Note: This README tracks the main branch, which may include unreleased changes. The latest npm release may not include every feature described here yet. See recent commits on main.

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.

If required configuration is not supplied through process environment variables or an .env file, an interactive wizard will guide you through setup. 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

start runs in the foreground by default. This is the recommended mode for systemd, Docker, local debugging, and other external process managers.

To run the bot in the built-in background mode instead:

opencode-telegram start --daemon
opencode-telegram status
opencode-telegram stop

Built-in daemon mode is intended for standalone npm installs without an external supervisor. For systemd, pm2, or Docker, keep using opencode-telegram start without --daemon.

For Linux systemd setup, see docs/LINUX_SYSTEMD_SETUP.md.

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.

When the current project i