grinev/opencode-telegram-bot

OpenCode mobile client via Telegram: run and monitor AI coding tasks from your phone while everything runs locally on your machine. OpenCode V2 support.

OpenCode Telegram Bot – What It Is

OpenCode Telegram Bot is a Node‑JS application that lets you control the OpenCode AI‑coding assistant (a local CLI tool) from a Telegram chat. It runs on the same machine as the OpenCode server and talks to Telegram’s Bot API, so no ports need to be opened to the internet.

Core capabilities

  • Remote prompting – send a text, voice, or file to the bot and have OpenCode generate code, which is returned as Telegram files.
  • Session handling – create, switch, abort, or detach from OpenCode sessions directly from chat commands.
  • Live tracking – the bot follows a running OpenCode session, showing progress, sub‑agent activity, and model usage in real time.
  • Model & agent switching – pick favourite models or change between Plan and Build agent modes on the fly.
  • File browsing – use /ls to explore the project’s directory tree, download files, or attach them to the next prompt.
  • Scheduled tasks – pre‑define prompts that run later or on a recurring interval.
  • Voice input – optional Whisper‑compatible speech‑to‑text conversion.
  • Security – only the Telegram user ID you specify can interact with the bot.
  • Localization – UI available in 12 languages.
  • Docker support – can be run inside a container while the OpenCode server stays on the host.

How you get it running

  1. Create a Telegram bot with @BotFather and note the token.
  2. Install OpenCode (the AI‑coding CLI) and start its server (opencode serve).
  3. Install the bot via npm (npx @grinev/opencode-telegram-bot@latest or a global install) and run the interactive wizard, which asks for the bot token, your Telegram user ID, OpenCode version (V1 or V2), API URL, and credentials.
  4. Chat with the bot – any plain text message becomes a prompt unless a blocking interaction (e.g., a menu) is active.

Main Telegram commands (selected)

Command What it does
/status Shows bot version, server health, current project, session and model
/new Starts a new OpenCode session
/abort Cancels the current task
/sessions Browse and switch recent sessions
/ls Interactive file browser
/settings Adjust runtime preferences
/task / /tasklist Create and manage scheduled prompts
/opencode_start / /opencode_stop Control the local OpenCode server from Telegram

Configuration

  • Environment variables or an .env file (stored in the OS‑specific app‑data folder) supply the bot token, allowed user ID, proxy settings, OpenCode server URL, version, and optional limits (e.g., TASK_LIMIT).
  • Local JSON command files placed in <appHome>/local-commands/ become custom /command shortcuts that run arbitrary shell commands on the host.

Who it’s for

Developers who already use OpenCode for AI‑assisted coding and want a convenient, secure way to interact with it from their phone while the server runs locally. It is not a standalone AI model; it is a thin client that forwards commands to the existing OpenCode service.

All details above are taken directly from the repository’s README.

Related

  • Project
    overwirehq/claude-code-telegram

    A Telegram bot that provides remote access to Claude Code, enabling developers to chat with their codebase, edit files, and run tests from any device.

  • Project
    giuliastro/harness-remote

    Harness Remote is an open‑source, local‑first control plane that lets you observe, pause, resume, and hand‑off native AI coding‑agent sessions (Codex, Claude, OpenCode, etc.) across devices. It runs a small Node.js gateway on a machine with a coding‑agent CLI, then connects via desktop, web, or Android clients. All code, credentials, and session data stay on your own machines; the tool only adds a UI and coordination layer.

  • Project
    tiann/hapi

    HAPI is a local-first tool that wraps official AI coding agents (Claude Code, Codex, Cursor Agent, etc.) so you can run and control their sessions remotely from iOS/Android apps, a web/PWA client, or Telegram Mini App. It supports seamless local↔remote handoff, phone-based approvals, remote terminal access, voice control, and an optional workspace browser. Setup is two npx commands; the web client is free, native apps are paid, and the relay is end-to-end encrypted via WireGuard + TLS.

  • Project
    anomalyco/opencode

    OpenCode is an open-source AI coding agent available as a CLI and a beta desktop app. It installs via curl script, npm, Homebrew, pacman, mise, or Nix. It includes two built-in agents — "build" (full-access, default) and "plan" (read-only) — switchable with Tab, plus a "general" subagent. Docs are at opencode.ai/v2/docs, and projects using "opencode" in their name must disclaim affiliation with the team.

  • Project
    termio-sh/termio

    Termio is a macOS (and iOS) application that creates a persistent, terminal‑first environment for AI coding agents. Sessions run in a daemon (`termiod`) so they survive app closures and can be accessed locally, via SSH on remote servers, or from a mobile companion. The UI offers project‑based organization, git worktree handling, split panes, a built‑in editor, live diff, and a status indicator that tells you when an agent needs human input. A rich CLI (`termio`) lets you spawn, control, and monitor agent sessions, while the roadmap adds a tmux‑like TUI, Android, Windows, and web clients.