opencode-telegram-bot

Accepts voice messages via Telegram, transcribes them to text using configurable STT providers (Whisper, Google Cloud Speech-to-Text, or local alternatives), sends the transcribed prompt to OpenCode as a coding task, and streams back responses with optional TTS synthesis for voice playback. The pipeline integrates grammy's voice message handling with the @opencode-ai/sdk's event stream, buffering audio chunks and managing provider-specific authentication and format conversion.

Consumes Server-Sent Events (SSE) from the OpenCode SDK's event stream, aggregates multi-event sequences (task start, model selection, context consumption, file changes, task completion) into a single coherent state, and maintains a persistent pinned Telegram message that updates in-place with live metrics: token usage, context window consumption, list of modified files, and agent status. Uses a SummaryAggregator class to deduplicate events, calculate deltas, and format structured data into Telegram's MarkdownV2 syntax.

Supports running the bot as a background daemon process on Linux/macOS using systemd or similar process managers. Provides configuration templates and setup guides for systemd service files, environment variable management, and log rotation. Enables the bot to start automatically on system boot and restart on failure, making it suitable for always-on local execution.

Implements comprehensive error handling for common failure scenarios: OpenCode server unavailable, invalid session/project, task submission errors, SSE connection drops, and API rate limits. Translates technical errors into user-friendly Telegram messages with suggested remediation steps (e.g., 'Server is offline, please check localhost:8000'). Includes retry logic for transient failures and graceful degradation when features are unavailable.

Provides a command-line interface (CLI) for starting the bot with configurable options: Telegram token, OpenCode server URL, STT/TTS provider selection, locale, and logging level. Parses arguments using a custom args parser, validates configuration, and loads environment variables from .env files. Supports both global npm installation (via npx) and direct execution, with clear error messages for missing or invalid configuration.

Implements a state machine that intercepts OpenCode agent questions and permission requests (e.g., 'Should I modify this file?', 'Which model should I use?') via SSE events, renders them as Telegram inline keyboard buttons, captures user responses, and sends them back to OpenCode via the SDK's interaction API. The Interaction Guard class manages state transitions, prevents concurrent interactions, and ensures responses are routed to the correct agent context (session, project, task).

Provides commands to list, create, and switch between OpenCode sessions and projects, mirroring the TUI's session management. Internally uses the OpenCode SDK to query available projects, manage git worktrees (creating isolated working directories for parallel work), and maintain session state (current project, branch, uncommitted changes). Stores session context in memory and persists it across bot restarts via environment variables or a local state file.

Accepts natural language scheduling descriptions (e.g., 'every Monday at 9am', 'daily at 3pm', 'once tomorrow at 2pm') via Telegram message, parses them using a scheduling library (likely node-cron or similar), generates cron expressions, and registers recurring or one-time tasks with the OpenCode server. The bot stores scheduled task definitions and executes them on a schedule, submitting the associated coding prompt to OpenCode at the specified time.

Captures modified files from OpenCode's file_changed SSE events, retrieves the full file content or diffs via the SDK, and delivers them to the user as Telegram file attachments (for binary or large files) or inline code blocks (for small text files). Supports syntax highlighting via Telegram's code block formatting and generates human-readable diffs showing before/after changes. Handles large files by splitting them into multiple messages or offering download links.

Exposes OpenCode's available agents (e.g., 'architect', 'coder', 'reviewer') and models (e.g., 'gpt-4', 'claude-3') via Telegram inline keyboard buttons, allowing users to select their preferred agent mode and model before submitting a task. Stores the selected agent and model in session state and applies them to all subsequent tasks until changed. Integrates with OpenCode's agent configuration API to fetch available options and validate selections.

Implements i18n support via a dictionary-based system that loads locale-specific strings from JSON files, allowing the bot to render all Telegram messages (commands, responses, errors, keyboard labels) in the user's preferred language. Supports dynamic locale switching per user and includes a contribution guide for adding new locales. Uses a key-based lookup system (e.g., 'task.started', 'error.no_session') to manage translations without hardcoding strings.

Establishes a persistent connection to a locally running OpenCode server (default: localhost:8000) using the @opencode-ai/sdk, consuming Server-Sent Events (SSE) to receive real-time updates on task progress, model usage, file changes, and agent questions. Handles connection lifecycle (connect, reconnect on failure, graceful shutdown), event parsing, and error handling. Translates SDK events into Telegram messages and maintains session context across the connection.

Accepts user prompts via Telegram messages (text or voice-transcribed), packages them with current session context (project, branch, uncommitted files, selected agent/model), and submits them to OpenCode as a task via the SDK. Preserves context across multiple messages by maintaining session state and allowing users to reference previous tasks or files. Handles prompt validation, context assembly, and error reporting.