package
Standalone bot that mirrors OpenCode sessions to Telegram topics
npm install opencode-telegram-mirrorGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
A standalone bot that mirrors OpenCode sessions to Telegram topics, enabling collaborative AI-assisted coding conversations in Telegram.
| Feature | Description |
|---|---|
| 📱 Real-time Streaming | Live responses with typing indicators, markdown, code blocks, and inline diffs |
| 🎯 Interactive Controls | Buttons for questions, permissions, mode switching, and session control |
| 📋 Slash Commands | /interrupt, /plan, /build, /review, /rename for quick actions |
| 🔍 Diff Viewer | Automatic diff generation with syntax highlighting and shareable links |
| 📸 Media Support | Send images and voice messages (transcribed via Whisper) as prompts |
| 🧵 Thread Support | Telegram forum threads with automatic title sync from OpenCode sessions |
| 💾 Session Persistence |
| Resume sessions across devices and restarts |
| 🔄 Multi-instance | Run multiple mirrors for different sessions/channels |
npm install -g opencode-telegram-mirrorCreate a Telegram Bot:
/newbot and follow instructionsGet your Chat ID:
Configure environment variables:
export TELEGRAM_BOT_TOKEN="your-bot-token"
export TELEGRAM_CHAT_ID="your-chat-id"
# Optional: export TELEGRAM_THREAD_ID="your-thread-id"Run the mirror in your project:
opencode-telegram-mirror .That's it! Your OpenCode session will now be mirrored to Telegram.
The Telegram mirror streams OpenCode session interactions (questions, answers, tool usage, and file edits) to Telegram topics. This enables:
Each instance of the opencode-telegram-mirror binary mirrors one OpenCode session to one Telegram channel/thread. This 1:1 mapping ensures clean separation between different coding conversations.
OpenCode Server Connection:
OPENCODE_URL: The mirror spawns its own OpenCode server instance locallyOPENCODE_URL: The mirror connects to an existing OpenCode server at the specified URLThis flexibility allows you to either run self-contained mirrors (each with their own server) or connect to a shared/managed OpenCode server.
Telegram supports threaded conversations in forum-style channels:
Each mirror instance should be configured with a unique TELEGRAM_THREAD_ID to prevent cross-contamination between different coding sessions.
While you can run a single mirror instance, production deployments typically require orchestration to support multiple concurrent sessions:
OPENCODE_URL for resource efficiencyExample orchestration might involve:
Single Instance (Simple Case):
If you're running one opencode-telegram-mirror instance with one Telegram bot and one channel, you don't need TELEGRAM_UPDATES_URL. The mirror will poll Telegram's API directly using getUpdates.
Multi-Instance Deployments:
When running multiple mirror instances (e.g., one per coding session or per team), Telegram only allows one webhook or one getUpdates poller per bot. To support multiple mirrors:
getUpdates once and distributes updates to multiple mirrorsTELEGRAM_UPDATES_URL: Point each mirror to this central endpointTELEGRAM_THREAD_IDUpdates URL API Contract: The central updates endpoint must accept GET requests with query parameters:
since: Last processed update_id (for pagination)chat_id: Filter updates to specific chatthread_id: Filter to specific thread (optional)Response format (JSON):
{
"updates": [
{
"payload": {
"update_id": 123,
"message": {
"message_id": 456,
"message_thread_id": 789,
"date": 1640995200,
"text": "Hello world",
"from": { "id": 123456, "username": "user" },
"chat": { "id": -1001234567890 }
}
},
"update_id": 123
}
]
}The payload contains the standard Telegram Update object. Basic authentication is supported via URL credentials (https://user:pass@example.com/updates).
opencode-telegram-mirror [directory] [session-id]directory: Working directory (defaults to current directory)session-id: Existing OpenCode session ID to resume| Variable | Description | Required |
|---|---|---|
TELEGRAM_BOT_TOKEN | Bot token from @BotFather | Yes |
TELEGRAM_CHAT_ID | Chat ID from @userinfobot | Yes |
TELEGRAM_THREAD_ID | Thread/topic ID for forum channels | No |
TELEGRAM_UPDATES_URL | Central updates endpoint for multi-instance deployments | No |
TELEGRAM_SEND_URL | Custom Telegram API endpoint (defaults to api.telegram.org) | No |
OPENCODE_URL | External OpenCode server URL (if not set, spawns local server) | No |
OPENAI_API_KEY | OpenAI API key for voice message transcription (Whisper) | No |
The bot loads configuration from (in order of priority):
~/.config/opencode/telegram.json<repo>/.opencode/telegram.jsonExample config file:
{
"botToken": "your-bot-token",
"chatId": "your-chat-id",
"threadId": 123,
"sendUrl": "https://api.telegram.org/bot",
"updatesUrl": "https://your-durable-object-endpoint"
}Send messages in Telegram to interact with OpenCode:
<title>: Rename the session and sync to Telegram threadSession titles are automatically synchronized between OpenCode and Telegram:
Voice messages are transcribed using OpenAI's Whisper API. To enable:
OPENAI_API_KEY in your environmentIf OPENAI_API_KEY is not set, the bot will respond with setup instructions when a voice message is received.
The bot provides inline keyboard controls for:
When OpenCode makes file edits, the bot:
# Clone the repo
git clone <repository-url>
cd opencode-telegram-mirror
# Install dependencies
bun install
# Run in development
bun run start
# Run tests
bun run test:run# Type check
bun run typecheck
# Run mock server for testing
bun run test:mock-server[Add your license here]
Estimated unpacked size across 7 packages.
1.4 MB
Includes dependencies.