That's it! Your OpenCode session will now be mirrored to Telegram.
How it works
The Telegram mirror streams OpenCode session interactions (questions, answers, tool usage, and file edits) to Telegram topics. This enables:
Collaborative coding: Share your coding sessions with team members
Remote pair programming: Get real-time feedback on your code
Session persistence: Keep conversations going across devices
Rich formatting: Code blocks, diffs, and interactive buttons
Architecture
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:
Without OPENCODE_URL: The mirror spawns its own OpenCode server instance locally
With OPENCODE_URL: The mirror connects to an existing OpenCode server at the specified URL
This flexibility allows you to either run self-contained mirrors (each with their own server) or connect to a shared/managed OpenCode server.
Threading & Topics
Telegram supports threaded conversations in forum-style channels:
No thread ID: Messages go to the main channel
With thread ID: Messages go to a specific topic thread within a forum channel
Each mirror instance should be configured with a unique TELEGRAM_THREAD_ID to prevent cross-contamination between different coding sessions.
Orchestration
While you can run a single mirror instance, production deployments typically require orchestration to support multiple concurrent sessions:
Multiple sessions: Run separate mirror processes for different coding projects
Thread isolation: Use unique thread IDs per session
Server sharing: Point multiple mirrors to the same OPENCODE_URL for resource efficiency
Load balancing: Distribute mirrors across multiple servers
Example orchestration might involve:
Docker containers for each mirror instance
Kubernetes deployments with unique environment configs
Process managers like PM2 for local deployment
Updates URL & Multi-Instance Deployments
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:
Central Updates Collector: Deploy a central service that polls getUpdates once and distributes updates to multiple mirrors
Set TELEGRAM_UPDATES_URL: Point each mirror to this central endpoint
Thread Isolation: Each mirror should have a unique TELEGRAM_THREAD_ID
Updates URL API Contract:
The central updates endpoint must accept GET requests with query parameters:
The payload contains the standard Telegram Update object. Basic authentication is supported via URL credentials (https://user:pass@example.com/updates).
Usage
Basic Usage
opencode-telegram-mirror [directory] [session-id]
directory: Working directory (defaults to current directory)
session-id: Existing OpenCode session ID to resume
Send voice messages to the bot - they'll be transcribed and sent to OpenCode
If OPENAI_API_KEY is not set, the bot will respond with setup instructions when a voice message is received.
Interactive Controls
The bot provides inline keyboard controls for:
Interrupt: Stop the current session
Mode switching: Toggle between "plan" and "build" modes
Questions: Answer multiple-choice questions from OpenCode
Permissions: Grant/deny file access permissions
Diff Viewer
When OpenCode makes file edits, the bot:
Generates a visual diff
Uploads it to a diff viewer
Shares a link to view the changes
Development
Prerequisites
Node.js 18+
npm or bun
Local Development
# Clone the repogit clone <repository-url>cd opencode-telegram-mirror# Install dependenciesbun install# Run in developmentbun run start# Run testsbun run test:run
Building
# Type checkbun run typecheck# Run mock server for testingbun run test:mock-server
Why Telegram?
Cross-platform: Works on any device with Telegram
Instant sync: Real-time message delivery
Rich formatting: Markdown, code blocks, and media support