Skip to content

2241812/tp-opencode

BranchesTags

Repository files navigation

tp-opencode

Python 3.10+ License: MIT OpenCode

Desktop GUI app for running OpenCode with a Telegram bot — one click to start everything. A lightweight OpenClaw alternative built for OpenCode.

Features

  • Desktop GUI — one-window app with setup wizard, server control, bot control, live logs, and model picker
  • One-command launch — opencode-telegram opens the GUI, auto-starts the server and bot
  • Remote coding — send prompts to OpenCode from Telegram, receive results on your phone
  • Session management — create, switch, rename, and abort sessions from Telegram or the GUI
  • Model picker — browse and switch models from the GUI dashboard
  • Agent modes — switch between Plan and Build modes with /mode
  • Voice prompts — send voice messages, transcribe via Whisper-compatible API
  • Scheduled tasks — schedule prompts to run later or on a recurring interval
  • Security — strict user ID whitelist; no external attack surface
  • Localization — English, Deutsch, Español, Français, Русский, 简体中文
  • Docker support — one-command deployment with docker-compose
  • CLI mode — run headless with opencode-telegram cli

Architecture

Telegram (your phone)
        │
        ▼
┌───────────────────────────────┐
│   OpenCode Telegram Bot       │
│   (Python · python-telegram)  │
│                               │
│  ┌─ Bot Handler               │
│  ├─ OpenCode API Client       │
│  ├─ Session Manager           │
│  ├─ Task Scheduler            │
│  ├─ Voice Transcriber (STT)   │
│  ├─ Text-to-Speech (TTS)      │
│  └─ Web GUI (Flask)           │
└──────────┬────────────────────┘
           │ HTTP / SSE
           ▼
┌───────────────────────────────┐
│   OpenCode Server             │
│   (localhost:4096)            │
│   opencode serve              │
└───────────────────────────────┘

Quick Start

1. Create a Telegram Bot

  1. Open @BotFather in Telegram and send /newbot
  2. Follow the prompts to choose a name and username
  3. Copy the bot token you receive

Get your Telegram User ID by messaging @userinfobot.

2. Install OpenCode

curl -fsSL https://opencode.ai/install | bash

3. Install & Launch the App

pip install tp-opencode
opencode-telegram

That's it. The GUI opens, you fill in your bot token and user ID on first launch, then click Start Server and Start Bot. Everything runs from one window.

From source

git clone https://github.com/2241812/tp-opencode.git
cd tp-opencode
pip install -e .
opencode-telegram

CLI mode (headless, no GUI)

opencode-telegram cli

Desktop GUI

The app opens a single window with everything you need:

  • Setup Wizard — on first launch, enter your bot token, user ID, and OpenCode URL
  • Dashboard — server status, bot status, model info at a glance
  • Start/Stop buttons — one click to start the OpenCode server and the Telegram bot
  • Live Logs — real-time log output from the bot
  • Model Picker — browse available models from your OpenCode config and select one
  • Session List — see recent sessions
  • Reconfigure — go back to the setup wizard anytime

Bot Commands

Command Description
/status Server health, current project, session, and model info
/new Create a new session
/abort Abort the current task
/sessions Browse and switch between recent sessions
/projects Switch between OpenCode projects
/mode Toggle between Plan and Build agent modes
/models Pick a model from available options
/compact Compact session context
/rename <title> Rename the current session
/commands Browse and run custom commands
/task <min> <prompt> Create a scheduled task
/tasklist Browse and delete scheduled tasks
/tts Toggle text-to-speech audio replies
/opencode_start Start the OpenCode server remotely
/opencode_stop Stop the OpenCode server remotely
/help Show available commands

Any regular text message is sent as a prompt to the coding agent.

Configuration

Environment Variables

Variable Description Required Default
TELEGRAM_BOT_TOKEN Bot token from @BotFather Yes —
TELEGRAM_ALLOWED_USER_ID Your numeric Telegram user ID Yes —
TELEGRAM_PROXY_URL Proxy URL for Telegram API (SOCKS5/HTTP) No —
OPENCODE_API_URL OpenCode server URL No http://localhost:4096
OPENCODE_SERVER_USERNAME Server auth username No opencode
OPENCODE_SERVER_PASSWORD Server auth password No —
OPENCODE_MODEL_PROVIDER Default model provider No opencode
OPENCODE_MODEL_ID Default model ID No big-pickle
BOT_LOCALE Bot UI language (en, de, es, fr, ru, zh) No en
RESPONSE_STREAMING Stream assistant replies No true
MESSAGE_FORMAT_MODE Reply formatting: markdown or raw No markdown
STT_API_URL Whisper-compatible API base URL (enables voice) No —
STT_API_KEY API key for STT provider No —
TTS_API_URL TTS API base URL No —
TTS_API_KEY TTS API key No —
WEB_GUI_ENABLED Enable monitoring web GUI No true
WEB_GUI_PORT Web GUI port No 8765
OPENCODE_AUTO_START Auto-start OpenCode server with bot No false
LOG_LEVEL Log level (debug, info, warn, error) No info

Voice Transcription

Set STT_API_URL and STT_API_KEY to enable voice message transcription:

# OpenAI Whisper
STT_API_URL=https://api.openai.com/v1
STT_API_KEY=your-key
STT_MODEL=whisper-1

# Groq
STT_API_URL=https://api.groq.com/openai/v1
STT_API_KEY=your-key
STT_MODEL=whisper-large-v3-turbo

Text-to-Speech

Set TTS_API_URL and TTS_API_KEY to enable spoken replies:

TTS_API_URL=https://api.openai.com/v1
TTS_API_KEY=your-key
TTS_MODEL=gpt-4o-mini-tts
TTS_VOICE=alloy

Toggle with /tts in the bot chat.

Web GUI

The built-in monitoring dashboard is available at http://localhost:8765 (configurable via WEB_GUI_PORT). It shows:

  • OpenCode server status
  • Current model and session info
  • Active sessions list
  • Scheduled tasks overview
  • JSON API at /api/status

Security

The bot enforces a strict user ID whitelist. Only the Telegram user whose numeric ID matches TELEGRAM_ALLOWED_USER_ID can interact with the bot. Messages from any other user are silently ignored.

Since the bot runs locally on your machine and connects to your local OpenCode server, there is no external attack surface beyond the Telegram Bot API itself.

Comparison with Alternatives

Feature This Bot grinev/opencode-telegram-bot OpenClaw
Language Python TypeScript TypeScript
Setup pip install + wizard npx + wizard Complex npm setup
Telegram ✅ ✅ ✅ (one of 20+ channels)
Web GUI ✅ (built-in) ❌ ✅
Voice STT/TTS ✅ ✅ ✅
Scheduled Tasks ✅ ✅ ✅ (cron)
Server Control ✅ ✅ ❌
Docker ✅ ❌ ✅
Scope Telegram-only, focused Telegram-only, focused Full platform, 20+ channels

Development

git clone https://github.com/2241812/tp-opencode.git
cd tp-opencode
pip install -e ".[dev]"

# Run with auto-reload
python -m opencode_telegram_bot.main

# Lint
ruff check src/

# Type check
mypy src/

# Tests
pytest tests/ -v

Project Structure

tp-opencode/
├── src/opencode_telegram_bot/
│   ├── api/
│   │   ├── client.py          # OpenCode HTTP API client
│   │   └── server.py          # OpenCode server process manager
│   ├── bot/
│   │   └── handler.py         # Telegram bot command handlers
│   ├── core/
│   │   ├── config.py          # Settings and configuration
│   │   └── session.py         # Session state management
│   ├── utils/
│   │   ├── i18n.py            # Localization system
│   │   ├── voice.py           # STT/TTS voice processing
│   │   └── scheduler.py       # Scheduled task manager
│   ├── web/
│   │   └── gui.py             # Flask monitoring dashboard
│   ├── locales/               # Translation files (en, ru, zh, de, es, fr)
│   ├── gui.py                 # Desktop GUI app (customtkinter)
│   └── main.py                # Entry point (defaults to GUI, cli for headless)
├── tests/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── pyproject.toml
└── README.md

Related Projects

License

MIT © 2241812

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages