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/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)
• 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
• Voice prompts — send voice/audio messages, transcribe them via a Whisper-compatible API, and optionally enable spoken replies with /tts
• 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
• 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)

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

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.

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

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

| Platform | Status | | -------- | -------------------------------------------- | | macOS | Fully supported | | Windows | Fully supported | | Linux | Fully supported (tested on Ubuntu 24.04 LTS) |

Bot Commands

| Command | Description | | ----------------- | ------------------------------------------------------- | | /status | Server health, current project, session, and model info | | /new | Create a new session | | /abort | Abort the current task | | /sessions | Browse and switch between recent sessions | | /projects | Switch between OpenCode projects | | /worktree | Switch between existing git worktrees | | /open | Add a project by browsing directories | | /tts | Toggle audio replies | | /rename | Rename the current session | | /commands | Browse and run custom commands | | /skills | Browse and run OpenCode skills | | /task | Create a scheduled task | | /tasklist | Browse and delete scheduled tasks | | /opencode_start | Start the local OpenCode server on the bot machine | | /opencode_stop | Stop the local OpenCode server on the bot machine | | /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.

When the current project is a git repository, /worktree shows the existing worktrees for that repository. Status and pinned updates display the main project path with the active branch, and show a separate Worktree line when a linked worktree is selected.

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
• If a recurring task is still running when its next interval arrives, the bot does not start a parallel copy of the same task and does not replay missed intervals later
• By default, the bot waits up to 120 minutes for one scheduled task run; change this with SCHEDULED_TASK_EXECUTION_TIMEOUT_MINUTES if needed
• 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

| Variable | Description