OpenCode Telegram Group Topics Bot
April 6, 2026 · View on GitHub
Languages: English (en), Deutsch (de), Espanol (es), Francais (fr), Russkiy (ru), Jian ti Zhong wen (zh-CN 中文说明)
A Telegram bot for OpenCode that turns one Telegram supergroup into a multi-session mobile workspace.
This project is a fork of the original single-chat bot: grinev/opencode-telegram-bot by Ruslan Grinev.
- Use the upstream project if you want the simpler single-chat workflow.
- Use this fork if you want one General control topic plus dedicated forum topics for parallel OpenCode sessions.
No open ports, no exposed web UI. The bot talks only to your local OpenCode server and the Telegram Bot API.
You can run many session topics in parallel inside one group, and many groups in parallel across different projects.
Platforms: macOS, Windows, Linux
Fork sync notes: FORK_SYNC.md
At a Glance
- One Telegram group usually maps to one repo / project workspace.
- The General topic is the control lane for
/projects,/sessions,/new, and status checks. - Each new OpenCode session gets its own forum topic.
- Each topic keeps its own session, model, agent, and pinned status state.
- Optional TTS replies can be toggled globally with
/ttsand persist across restarts. - Subagent child-session work is summarized back into the parent topic as live status cards.
- Multiple topics can run at the same time, and multiple groups can be active at the same time.
- DMs are for light control/status usage, not the main multi-session workflow.
Quick Start
1. Prerequisites
- Install Node.js 20+
- Install OpenCode from opencode.ai or GitHub
- Create a Telegram bot with @BotFather
- Get your Telegram numeric user ID from @userinfobot
2. Create and Prepare the Telegram Group
- Create a new Telegram supergroup for one OpenCode project/repository.
- Add your bot to that group.
- Make the bot an admin with permission to Manage Topics.
- Enable Topics in the group settings.
- In @BotFather, run
/setprivacyfor the bot and choose Disable. - Keep the default General topic - that is the control lane.
3. Start OpenCode
Run OpenCode on the machine where the bot will live:
opencode serve
Default API URL: http://localhost:4096
4. Install the Bot
Option A: npx
npx opencode-telegram-group-topics-bot
Option B: Global install
npm install -g opencode-telegram-group-topics-bot
opencode-telegram-group-topics-bot config
opencode-telegram-group-topics-bot start
Option C: Run from source
git clone https://github.com/shanekunz/opencode-telegram-group-topics-bot.git
cd opencode-telegram-group-topics-bot
npm install
npm run build
node dist/cli.js config --mode sources
npm run dev
dist/cli.js is the compiled CLI entrypoint produced by npm run build.
5. Complete the Setup Wizard
The wizard asks for:
- interface language
- Telegram bot token
- allowed Telegram user ID
- OpenCode API URL
- optional OpenCode server username/password
6. First-Time Verification
- Open a DM with your bot and run
/start. - Confirm the bot replies.
- Open your Telegram group and run
/startin General. - Run
/statusand confirm the bot can reach OpenCode. - Run
/projectsin General and pick the repo for this group. - Run
/newin General to create a session topic. - Open the new topic and send a prompt.
If that works, your group workspace is ready.
Daily Workflow
- Start OpenCode with
opencode serve - Start the bot
- Open the Telegram group and go to General
- Use
/projectsto confirm the selected repo - Use
/newto create a new session topic - Work inside the topic thread
- Use
/sessionsin General to revisit older session lanes
Parallel Workloads and Telegram Rate Limits
- This fork is designed for parallel work: many topic threads in one group, and many groups across projects.
- Telegram enforces message rate limits, especially when many topics are receiving updates at once.
- The bot handles those limits gracefully and slows or staggers Telegram updates when needed.
- Your OpenCode sessions continue running even if Telegram updates become less frequent.
- In heavy parallel usage, expect less real-time chatter per topic, but not lost OpenCode work.
Commands
| Command | Description |
|---|---|
/status | Server health, current project, session, and model info |
/new | Create a new session topic |
/abort | Abort the current task |
/sessions | Browse and switch between recent sessions |
/projects | Switch between OpenCode projects |
/tts | Toggle audio replies globally |
/rename | Rename the current session |
/commands | Browse and run custom commands |
/task | Create a scheduled task for the current project |
/tasklist | List and delete scheduled tasks for the current project |
/opencode_start | Start the OpenCode server remotely |
/opencode_stop | Stop the OpenCode server remotely |
/help | Show available commands |
Any normal text message in a session topic is treated as a prompt when no blocking interaction is active.
How This Fork Differs From Upstream
| Topic | Upstream | This fork |
|---|---|---|
| Main UX | One chat | One group with forum topics |
| Session layout | Switch sessions in one lane | One topic per session lane |
| Best for | Simplicity | Parallel mobile workflows |
| Complexity | Lower | Higher |
If you want the simpler path, use the upstream project.
Configuration
Config Location
- Source mode stores config in the repository root.
- Installed mode stores config in the platform app-data directory.
OPENCODE_TELEGRAM_HOMEoverrides both and forces a custom config directory.
Installed-mode config paths:
- macOS:
~/Library/Application Support/opencode-telegram-group-topics-bot/.env - Windows:
%APPDATA%\opencode-telegram-group-topics-bot\.env - Linux:
~/.config/opencode-telegram-group-topics-bot/.env
Environment Variables
| 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 (en, de, es, fr, ru, zh) | No | en |
SESSIONS_LIST_LIMIT | Sessions per page in /sessions | No | 10 |
PROJECTS_LIST_LIMIT | Projects per page in /projects | No | 10 |
COMMANDS_LIST_LIMIT | Commands per page in /commands | No | 10 |
SCHEDULED_TASK_POLL_INTERVAL_SEC | Scheduled task poll interval in seconds | No | 30 |
SERVICE_MESSAGES_INTERVAL_SEC | Service messages interval; 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 | No | false |
MESSAGE_FORMAT_MODE | Assistant reply formatting mode: markdown or raw | No | markdown |
RESPONSE_STREAM_THROTTLE_MS | Delay between streamed assistant updates in ms | No | 1000 |
BASH_TOOL_DISPLAY_MAX_LENGTH | Maximum displayed length for bash tool commands in Telegram summaries | No | 128 |
CODE_FILE_MAX_SIZE_KB | Max file size (KB) to send as a document | No | 100 |
STT_API_URL | Whisper-compatible API base URL | 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 | No | - |
TTS_API_URL | TTS API base URL | No | - |
TTS_API_KEY | TTS API key | No | - |
TTS_MODEL | TTS model name passed to /audio/speech | No | gpt-4o-mini-tts |
TTS_VOICE | OpenAI-compatible TTS voice name | No | alloy |
LOG_LEVEL | Log level (debug, info, warn, error) | No | info |
Keep your .env private. It contains your bot token.
Optional: Voice and Audio Transcription
If STT_API_URL and STT_API_KEY are set, the bot can transcribe Telegram voice/audio messages before sending them to OpenCode.
If TTS credentials are configured, you can toggle spoken replies globally with /tts. The preference is stored in settings.json and persists across restarts.
TTS configuration example:
TTS_API_URL=https://api.openai.com/v1
TTS_API_KEY=your-tts-api-key
TTS_MODEL=gpt-4o-mini-tts
TTS_VOICE=alloy
Whisper-compatible examples:
- OpenAI:
https://api.openai.com/v1 - Groq:
https://api.groq.com/openai/v1 - Together:
https://api.together.xyz/v1
Model Picker Notes
- Favorites are shown before recent models
- The current model is marked with
✅ - The default model from
OPENCODE_MODEL_PROVIDER+OPENCODE_MODEL_IDis always included
To add favorites, open the OpenCode TUI and press Cmd+F / Ctrl+F on a model.
Features
- Thread-scoped OpenCode sessions inside Telegram forum topics
- Scheduled tasks with a dedicated per-project scheduled topic in forum groups
- Pinned live status messages per topic
- Live assistant response streaming and streamed tool-call updates
- Model, agent, variant, and context controls from the keyboard
- Custom OpenCode command execution
- Interactive permission and question handling
- Voice/audio transcription support
- File attachments for images, PDFs, and text files
- Strict single-user access control
Security
Only the Telegram user whose ID matches TELEGRAM_ALLOWED_USER_ID can use the bot.
Since the bot runs locally and connects to your local OpenCode server, there is no exposed public service beyond Telegram itself.
Development
Run from source
git clone https://github.com/shanekunz/opencode-telegram-group-topics-bot.git
cd opencode-telegram-group-topics-bot
npm install
npm run build
node dist/cli.js config --mode sources
npm run dev
Scripts
| Script | Description |
|---|---|
npm run dev | Build and start |
npm run build | Compile TypeScript |
npm start | Run compiled code |
npm run release:notes:preview | Preview release notes |
npm run lint | Run ESLint |
npm run format | Run Prettier |
npm test | Run tests |
npm run test:coverage | Run tests with coverage |
No watcher is used because the bot maintains persistent SSE and polling connections.
Troubleshooting
Bot does not respond
- Confirm
TELEGRAM_ALLOWED_USER_IDmatches your real Telegram user ID - Confirm the bot token is correct
- Make sure you disabled privacy mode in BotFather for group usage
OpenCode server is unavailable
- Make sure
opencode serveis running - Confirm
OPENCODE_API_URLpoints to the correct address
Cannot create new session topics
- Confirm the group is a supergroup with Topics enabled
- Confirm the bot is an admin with Manage Topics permission
- Run
/newfrom General, not inside an existing session topic
No models appear in the picker
- Add favorites in the OpenCode TUI
- Confirm
OPENCODE_MODEL_PROVIDERandOPENCODE_MODEL_IDare valid for your setup
Linux permission issues
- Check the CLI binary is executable:
chmod +x $(which opencode-telegram-group-topics-bot) - Check the config directory is writable:
~/.config/opencode-telegram-group-topics-bot/
Contributing
Please follow CONTRIBUTING.md.
Community
Open issues in this repository for this fork. For upstream discussion, see grinev/opencode-telegram-bot.
License
MIT • Original project © Ruslan Grinev • Fork changes © Shane Kunz