Skip to content

Commit a5b34a6

Browse files
22418122241812
committed
feat: initial release of OpenCode Telegram Bot
Python-based Telegram client for OpenCode CLI — run and monitor AI coding tasks from your phone while everything runs locally. Features: - Remote coding via Telegram with session management - Live status updates, model switching, agent modes - Voice transcription (STT) and text-to-speech (TTS) - Scheduled tasks with interval/cron support - Built-in Flask web monitoring GUI - Docker support with docker-compose - 6 locale translations (en, ru, zh, de, es, fr) - Strict user ID whitelist security Inspired by grinev/opencode-telegram-bot (TypeScript) and OpenClaw, built in Python for simpler setup and customization.
0 parents  commit a5b34a6

37 files changed

Lines changed: 2878 additions & 0 deletions

‎.env.example‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Telegram
2+
TELEGRAM_BOT_TOKEN=
3+
TELEGRAM_ALLOWED_USER_ID=
4+
TELEGRAM_PROXY_URL=
5+
6+
# OpenCode Server
7+
OPENCODE_API_URL=http://localhost:4096
8+
OPENCODE_SERVER_USERNAME=opencode
9+
OPENCODE_SERVER_PASSWORD=
10+
11+
# Model
12+
OPENCODE_MODEL_PROVIDER=opencode
13+
OPENCODE_MODEL_ID=big-pickle
14+
15+
# Bot
16+
BOT_LOCALE=en
17+
SESSIONS_LIST_LIMIT=10
18+
PROJECTS_LIST_LIMIT=10
19+
COMMANDS_LIST_LIMIT=10
20+
TASK_LIMIT=10
21+
BASH_TOOL_DISPLAY_MAX_LENGTH=128
22+
SERVICE_MESSAGES_INTERVAL_SEC=5
23+
HIDE_THINKING_MESSAGES=false
24+
HIDE_TOOL_CALL_MESSAGES=false
25+
RESPONSE_STREAMING=true
26+
MESSAGE_FORMAT_MODE=markdown
27+
CODE_FILE_MAX_SIZE_KB=100
28+
29+
# Voice (STT)
30+
STT_API_URL=
31+
STT_API_KEY=
32+
STT_MODEL=whisper-large-v3-turbo
33+
STT_LANGUAGE=
34+
35+
# TTS
36+
TTS_API_URL=
37+
TTS_API_KEY=
38+
TTS_MODEL=gpt-4o-mini-tts
39+
TTS_VOICE=alloy
40+
41+
# Web GUI
42+
WEB_GUI_ENABLED=true
43+
WEB_GUI_HOST=127.0.0.1
44+
WEB_GUI_PORT=8765
45+
46+
# Logging
47+
LOG_LEVEL=info
48+
49+
# OpenCode Server Management
50+
OPENCODE_COMMAND=opencode
51+
OPENCODE_WORK_DIR=
52+
OPENCODE_AUTO_START=false

‎.gitignore‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
7+
# Distribution / packaging
8+
dist/
9+
build/
10+
*.egg-info/
11+
*.egg
12+
13+
# Virtual environments
14+
.venv/
15+
venv/
16+
env/
17+
18+
# IDE
19+
.vscode/
20+
.idea/
21+
*.swp
22+
*.swo
23+
24+
# Environment variables
25+
.env
26+
.env.local
27+
.env.*.local
28+
29+
# Runtime data
30+
data/
31+
*.db
32+
*.sqlite3
33+
sessions/
34+
settings.json
35+
36+
# Logs
37+
*.log
38+
logs/
39+
40+
# OS
41+
.DS_Store
42+
Thumbs.db
43+
44+
# Docker
45+
docker-compose.override.yml
46+
47+
# Testing
48+
.coverage
49+
htmlcov/
50+
.pytest_cache/
51+
52+
# MyPy
53+
.mypy_cache/

‎AGENTS.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# AGENTS.md
2+
3+
This is an OpenCode Telegram Bot project — a Python-based Telegram client for [OpenCode](https://github.com/anomalyco/opencode) CLI.
4+
5+
## Architecture
6+
7+
- **src/opencode_telegram_bot/api/** — OpenCode HTTP API client and server process manager
8+
- **src/opencode_telegram_bot/bot/** — Telegram bot command handlers and message routing
9+
- **src/opencode_telegram_bot/core/** — Configuration, settings, and session state management
10+
- **src/opencode_telegram_bot/utils/** — i18n, voice transcription (STT/TTS), task scheduler
11+
- **src/opencode_telegram_bot/web/** — Flask-based monitoring web GUI
12+
- **src/opencode_telegram_bot/locales/** — Translation files for multiple languages
13+
14+
## Key Dependencies
15+
16+
- `python-telegram-bot` — Telegram Bot API
17+
- `httpx` — Async HTTP client for OpenCode API
18+
- `pydantic-settings` — Environment-based configuration
19+
- `apscheduler` — Scheduled task management
20+
- `flask` — Web monitoring GUI
21+
- `openai` — Whisper-compatible STT/TTS client
22+
23+
## Commands
24+
25+
```bash
26+
# Start the bot
27+
opencode-telegram
28+
29+
# Run configuration wizard
30+
opencode-telegram config
31+
32+
# Development
33+
pip install -e ".[dev]"
34+
ruff check src/
35+
mypy src/
36+
pytest tests/ -v
37+
38+
# Docker
39+
docker compose up -d
40+
```
41+
42+
## OpenCode API Integration
43+
44+
The bot communicates with OpenCode's HTTP API at `http://localhost:4096` by default. Key endpoints:
45+
- `GET /health` — Server health check
46+
- `GET/POST /api/projects` — Project management
47+
- `GET/POST /api/sessions` — Session CRUD
48+
- `GET/POST /api/models` — Model management
49+
- `POST /api/sessions/{id}/message` — Send prompts
50+
- `GET /api/sessions/{id}/events` — SSE event stream for live responses

‎CONTRIBUTING.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Contributing to OpenCode Telegram Bot
2+
3+
Thank you for your interest in contributing! This project is inspired by the work done in [grinev/opencode-telegram-bot](https://github.com/grinev/opencode-telegram-bot) and aims to provide a Python-based alternative for easier setup and customization.
4+
5+
## Development Setup
6+
7+
```bash
8+
git clone https://github.com/2241812/opencode-telegram-bot.git
9+
cd opencode-telegram-bot
10+
pip install -e ".[dev]"
11+
```
12+
13+
## Code Style
14+
15+
This project uses:
16+
- **ruff** for linting and formatting
17+
- **mypy** for type checking
18+
19+
```bash
20+
ruff check src/ tests/
21+
ruff format src/ tests/
22+
mypy src/
23+
```
24+
25+
## Running Tests
26+
27+
```bash
28+
pytest tests/ -v
29+
pytest tests/ -v --cov=opencode_telegram_bot
30+
```
31+
32+
## Adding a New Locale
33+
34+
1. Create a new directory under `src/opencode_telegram_bot/locales/<code>/`
35+
2. Copy `locales/en/messages.json` as a template
36+
3. Translate all string values
37+
4. The locale will be auto-detected by the setup wizard
38+
39+
## Pull Request Guidelines
40+
41+
- Follow the existing code style (ruff + mypy clean)
42+
- Add tests for new features
43+
- Update documentation if changing user-facing behavior
44+
- Keep commits focused and atomic
45+
- Reference related issues in commit messages
46+
47+
## Commit Convention
48+
49+
Use conventional commits:
50+
- `feat:` new feature
51+
- `fix:` bug fix
52+
- `docs:` documentation changes
53+
- `refactor:` code refactoring
54+
- `test:` adding or updating tests
55+
- `chore:` maintenance tasks
56+
57+
## Related
58+
59+
- [OpenCode](https://github.com/anomalyco/opencode) — The open source AI coding agent
60+
- [OpenCode Telegram Bot (TypeScript)](https://github.com/grinev/opencode-telegram-bot) — Original Telegram bot implementation

‎Dockerfile‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
FROM python:3.12-slim
2+
3+
WORKDIR /app
4+
5+
COPY requirements.txt .
6+
RUN pip install --no-cache-dir -r requirements.txt
7+
8+
COPY src/ ./src/
9+
COPY pyproject.toml .
10+
11+
RUN pip install -e .
12+
13+
EXPOSE 8765
14+
15+
ENV PYTHONUNBUFFERED=1
16+
17+
CMD ["opencode-telegram"]

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 2241812
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)