Skip to content

PRODUCT.md

Latest commit

 

History

History
180 lines (136 loc) · 8.36 KB

PRODUCT.md

File metadata and controls

180 lines (136 loc) · 8.36 KB
Raw

OpenCode Telegram Bridge

Telegram bot client for OpenCode that lets you run and monitor coding tasks on your local machine from Telegram.

This fork extends the original single-chat bot with thread-scoped group workflows: the General topic acts as the control lane, and each created topic can host its own OpenCode session.

Fork maintenance notes live in FORK_SYNC.md.

Concept

The app works as a bridge between Telegram and a locally running OpenCode server:

  • You send prompts from Telegram
  • The bot forwards them to OpenCode
  • The app listens to OpenCode SSE events
  • Results are aggregated and sent back in Telegram-friendly format

No public inbound ports are required for normal usage.

Target Usage Scenario

  1. The user works on a project locally with OpenCode (Desktop/TUI).
  2. They finish the local session and leave the computer.
  3. Later, while away, they run this bridge service and connect via Telegram.
  4. In a forum-enabled supergroup, they use the General topic to manage projects and create new session topics.
  5. Each session topic becomes an independent coding lane with its own session, status, and pinned updates.
  6. They send coding tasks and receive periodic progress updates.
  7. They receive completed assistant responses in chat and continue the workflow asynchronously.

Functional Requirements

OpenCode server management

  • Check OpenCode server status (running / not running)
  • Start OpenCode server from the app (opencode serve)
  • Stop OpenCode server from the app

Project management

  • Fetch available projects from OpenCode API (name + path)
  • Select and switch projects
  • Persist selected project between restarts (settings.json)

Session management

  • Fetch last N sessions (name + date)
  • Select and attach to an existing session
  • Create a new session
  • Use OpenCode-generated session title (based on conversation)

Task handling

  • Send text prompts to OpenCode
  • Accept voice/audio messages, transcribe via Whisper-compatible STT API, and forward recognized text as prompts
  • Optionally send a TTS audio file of the final assistant reply in addition to text when /tts is enabled globally
  • Interrupt current task (ESC equivalent)
  • Handle OpenCode questions with inline options and custom text answers
  • Send selected/custom answers back to OpenCode (question.reply)
  • Handle permission requests interactively (allow once / always / reject)

Result delivery

  • Send each completed assistant response after completion signal from SSE
  • Optionally attach a TTS audio file for completed replies when /tts is enabled globally
  • Do not expose raw chain-of-thought; send a lightweight thinking indicator instead
  • Split long responses into multiple Telegram messages
  • Send code updates as files (size-limited)

Session status in chat

  • Keep a pinned status message in the chat
  • Show session title, project, model, context usage, and changed files
  • Auto-update status from SSE and tool events
  • Preserve pinned message ID across bot restarts

Security

  • Whitelist by Telegram user ID (single-user mode)
  • Ignore messages from non-authorized users

Configuration

  • Telegram bot token
  • Allowed Telegram user ID
  • Default model provider and model ID
  • Selected project persisted in settings.json
  • Configurable sessions list size (default: 10)
  • Configurable bot locale
  • Configurable visibility for service messages (thinking/tool calls)
  • Configurable max code file size in KB (default: 100)
  • Optional STT settings for voice transcription (STT_API_URL, STT_API_KEY, STT_MODEL, STT_LANGUAGE)
  • Optional TTS credentials for global audio replies (TTS_API_URL, TTS_API_KEY, TTS_MODEL, TTS_VOICE); reply behavior is toggled with /tts

Current Product Scope

Bot commands

Current command set:

  • /status - server, project, and session status
  • /new - create a new session
  • /abort - stop the current task
  • /sessions - show and switch recent sessions
  • /projects - show and switch projects
  • /open - add and select a project by browsing allowed directories
  • /rename - rename current session
  • /commands - browse and run custom commands (plus built-ins like init and review)
  • /task - create a scheduled task for the current project
  • /tasklist - list and delete scheduled tasks for the current project
  • /opencode_start - start local OpenCode server
  • /opencode_stop - stop local OpenCode server
  • /help - show command help

Model, agent, variant, and context actions are available from the persistent bottom keyboard.

Text messages (non-commands) are treated as prompts for OpenCode only when no blocking interaction is active. Voice/audio messages are transcribed and then sent as prompts when STT is configured. When /tts is enabled globally, completed assistant replies also include a generated audio file if TTS is configured.

Interaction routing rules:

  • Only one interactive flow can be active at a time (inline menu, permission, question, rename, commands, scheduled task creation)
  • While an interaction is active, unrelated input is blocked with a contextual hint
  • Allowed utility commands during active interactions: /help, /status, /abort
  • Unknown slash commands return an explicit fallback message
  • Interaction flows do not expire automatically and wait for explicit completion (answer, cancel, /abort, reset/cleanup)

Model picker behavior:

  • Uses OpenCode local model state (favorite + recent)
  • Favorites are shown first, recent models are shown after favorites
  • Models already present in favorites are not duplicated in recent
  • Default configured model (OPENCODE_MODEL_PROVIDER + OPENCODE_MODEL_ID) is treated as favorite

Main features already implemented

  • OpenCode server control and health checks via bot commands
  • Project management (list/switch) with inline menus
  • Session management (list/switch/create) with inline menus
  • Group-threaded workflow with General control topic plus per-session forum topics
  • Prompt execution through OpenCode with SSE-based event handling
  • Live assistant response streaming with thread-aware Telegram edits and fallback completion delivery
  • Subagent work status cards routed back into the parent topic thread
  • Interactive question and permission flows (buttons + custom text answers)
  • Single-active interaction routing with contextual blocking and cleanup recovery
  • Pinned status updates (session, project, model, context usage, changed files)
  • Session cost tracking in scoped pinned messages
  • Model and agent selection from Telegram (favorites first, recent next, no duplicates)
  • Context/variant controls from Telegram keyboard
  • Scheduled tasks with dedicated per-project scheduled topics in forum groups
  • Sending code blocks as files when needed
  • Configurable batching of service messages (thinking + tool updates): recommended >=2 sec for Telegram rate limits; 0 = immediate
  • Configurable service message visibility via env flags (HIDE_THINKING_MESSAGES, HIDE_TOOL_CALL_MESSAGES)
  • Voice/audio transcription via Whisper-compatible APIs (OpenAI/Groq/Together and compatible providers)
  • Optional global audio replies with /tts via OpenAI-compatible APIs
  • Single-user security model (allowed Telegram user ID)
  • Persistent bot settings (settings.json) between restarts
  • Localization structure via dedicated i18n files

Current Task List

Open tasks for upcoming iterations:

  • Display MCP servers, formatters, and plugins in bot status/details
  • Configure visibility level for thinking and intermediate steps
  • Add server crash notifications in Telegram
  • Add periodic health checks and optional auto-restart for OpenCode server
  • Improve Telegram-compatible message formatting for richer outputs
  • Support sending photos from Telegram to OpenCode (screenshots, images)
  • Support sending PDF documents from Telegram to OpenCode
  • Support sending text files from Telegram to OpenCode (code, configs, etc.)
  • Add scheduled tasks
  • Provide a Docker image and basic container deployment guide
  • Add voice transcription

Possible Improvements

Optional or longer-term enhancements:

  • Create new OpenCode projects directly from Telegram
  • Add project file browsing helpers (for example, ls and open flows)
  • Improve support for git worktree-based workflows