https://github.com/grinev/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.
https://github.com/grinev/opencode-telegram-bot
ai-agent coding-agent developer-tools grammy nodejs opencode sse telegrambot typescript
Last synced: 20 days ago
JSON representation
OpenCode Telegram bot client for OpenCode CLI: run and monitor AI coding tasks from your phone while everything runs locally on your machine.
- Host: GitHub
- URL: https://github.com/grinev/opencode-telegram-bot
- Owner: grinev
- License: mit
- Created: 2026-02-09T11:13:23.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-02-26T00:11:18.000Z (24 days ago)
- Last Synced: 2026-02-26T05:50:40.178Z (24 days ago)
- Topics: ai-agent, coding-agent, developer-tools, grammy, nodejs, opencode, sse, telegrambot, typescript
- Language: TypeScript
- Homepage:
- Size: 11.3 MB
- Stars: 50
- Watchers: 1
- Forks: 9
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# OpenCode Telegram Bot
[](https://www.npmjs.com/package/@grinev/opencode-telegram-bot)
[](https://github.com/grinev/opencode-telegram-bot/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org)
OpenCode Telegram Bot is a secure Telegram client for [OpenCode](https://opencode.ai) 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.
Platforms: macOS, Windows, Linux
Languages: English (`en`), Deutsch (`de`), Español (`es`), Русский (`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
- **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](https://nodejs.org)
- **OpenCode** — install from [opencode.ai](https://opencode.ai) or [GitHub](https://github.com/sst/opencode)
- **Telegram Bot** — you'll create one during setup (takes 1 minute)
## Quick Start
### 1. Create a Telegram Bot
1. Open [@BotFather](https://t.me/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](https://t.me/userinfobot) and it will reply with your numeric ID.
### 2. Start OpenCode Server
Start the OpenCode server:
```bash
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`:
```bash
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](#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, and OpenCode API URL. After that, you're ready to go. Open your bot in Telegram and start sending tasks.
#### Alternative: Global Install
```bash
npm install -g @grinev/opencode-telegram-bot
opencode-telegram start
```
To reconfigure at any time:
```bash
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 |
| `/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` | Sessions per page in `/sessions` | No | `10` |
| `PROJECTS_LIST_LIMIT` | Projects per page 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 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
```bash
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:
```bash
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](https://t.me/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](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](https://github.com/grinev/opencode-telegram-bot/discussions).
## License
[MIT](LICENSE) © Ruslan Grinev