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.

OpenCode Telegram Bot – What it is

A Node‑JS Telegram bot that lets you control the OpenCode AI‑coding CLI from your phone. It talks only to a local OpenCode server (running on the same machine) and the official Telegram Bot API – no public ports or exposed APIs are required. In practice you can start a coding session, switch models, send files, get live updates, and even schedule jobs, all from a Telegram chat.

Core capabilities (as described in the README)

Area	What you can do from Telegram
Remote coding	Send any text prompt (or voice‑transcribed prompt) to OpenCode and receive the generated code back as files.
Session handling	Create new sessions (`/new`), continue existing ones (`/sessions`), rename (`/rename`), abort (`/abort`), detach (`/detach`).
Live tracking	The bot follows a running OpenCode CLI session, showing live agent output, sub‑agent steps, and any external input coming from another TUI client.
Model management	Pick a model from your OpenCode favorites or recent history, or browse all models by provider, directly in the chat.
Agent modes	Switch between Plan and Build modes on the fly; watch sub‑agent activity.
Skills & commands	Browse OpenCode “skills” or custom commands (`/skills`, `/commands`) and run them with optional arguments.
File interaction	Upload images, PDFs, or any text‑based file; use `/ls` to browse the project’s filesystem, download files, or attach a file to the next prompt.
Scheduled tasks	Create one‑off or recurring prompts (`/task`, `/tasklist`). Recurring jobs run at a minimum interval of 5 min, up to 10 tasks by default.
Status & notifications	A pinned message constantly shows project/worktree, model, context usage, and changed files. Background‑session notifications keep you informed of detached sessions.
Settings & localisation	`/settings` lets you tweak runtime options (message queue, context compaction, STT, etc.). UI is available in 10 languages via `BOT_LOCALE`.
Security	Only the Telegram user ID you whitelist can talk to the bot; all other users are ignored.
Docker & daemon mode	Run the bot inside a container while OpenCode stays on the host, or use the built‑in daemon (`opencode‑telegram start --daemon`).

Getting started (quick‑start flow)

Create a Telegram bot with @BotFather and note the token.
Find your Telegram numeric user ID via @userinfobot.
Start the OpenCode server on the same machine: opencode serve (default API URL http://localhost:4096).
Run the bot – the easiest way is a one‑liner:
```
npx @grinev/opencode-telegram-bot@latest
```
If any required env vars are missing, an interactive wizard will ask for the token, user ID, API URL, etc., and write an .env file to the platform‑specific config directory.
Open Telegram, start a chat with your new bot, and begin sending prompts.

Alternative installation – npm i -g @grinev/opencode-telegram-bot then opencode-telegram start. Use --daemon for a self‑contained background process, or integrate with systemd/pm2/Docker as described in the docs.

Configuration highlights

Variable	Meaning	Typical default
`TELEGRAM_BOT_TOKEN`	Bot token from BotFather	required
`TELEGRAM_ALLOWED_USER_ID`	Your numeric Telegram ID	required
`OPENCODE_API_URL`	URL of the local OpenCode server	`http://localhost:4096`
`OPENCODE_MODEL_PROVIDER` / `OPENCODE_MODEL_ID`	Default model to use when none is selected	`opencode` / `big-pickle`
`BOT_LOCALE`	UI language (`en`, `es`, `zh`, …)	`en`
`MESSAGE_QUEUE` (via `/settings`)	Queue messages while the agent is busy	off by default
`TASK_LIMIT`	Max concurrent scheduled tasks	`10`
`SCHEDULED_TASK_EXECUTION_TIMEOUT_MINUTES`	How long the bot waits for a scheduled run before marking it failed	`120`

All of these can be supplied via an .env file or real environment variables; the wizard writes the file to ~/Library/Application Support/opencode-telegram-bot/.env (macOS), %APPDATA%\opencode-telegram-bot\.env (Windows) or ~/.config/opencode-telegram-bot/.env (Linux).

Who would use this?

Developers who already use OpenCode locally and want a mobile‑first way to fire off coding tasks while away from their workstation.
Teams that need a quick, secure remote interface without exposing ports or setting up a full web UI.
Power users who like Telegram bots for their interactivity (inline keyboards, pinned messages, voice‑to‑text, etc.).

Limitations / notes from the README

The bot only works when the OpenCode server runs on the same machine as the bot (or is reachable via the configured OPENCODE_API_URL).
Scheduled tasks always run with the build agent; other agents are not currently supported for recurring jobs.
The npm package may lag behind the main branch – some features shown in the README might not be present in the latest released version.
The maximum file size for document upload is configurable (CODE_FILE_MAX_SIZE_KB), but the default is not listed in the excerpt.

Bottom line

OpenCode Telegram Bot is a genuine, production‑grade bridge between the OpenCode AI‑coding platform and Telegram, giving you a secure, portable UI for remote code generation, session management, and automation. It stays entirely local, supports multiple languages, and offers a rich set of Telegram‑native interactions (inline keyboards, pinned status, voice prompts, file browsing). If you already rely on OpenCode for AI‑assisted development, this bot lets you extend that workflow onto your phone without opening any network ports.