Metadata-Version: 2.4
Name: telegram-opencode-bridge-bot
Version: 0.1.6
Summary: A Telegram bot that bridges messages directly to OpenCode — an AI coding agent running on your machine
Author-email: MaheshNagabhairava <maheshnagabhirava12345@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MaheshNagabhairava/telegram-opencode-bridge-bot
Keywords: telegram,bot,opencode,ai,coding,bridge
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: python-telegram-bot[ext]>=21.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiosqlite>=0.19.0

# 🤖 Telegram → OpenCode Bridge Bot

A lightweight Python bot that bridges your Telegram messages directly to [OpenCode](https://opencode.ai) — an AI coding agent running on your machine. Think of it as having Claude/GPT-powered coding assistance right in your pocket via Telegram.

## ✨ Features

- **Direct OpenCode integration** — routes your messages to OpenCode's HTTP API
- **Persistent sessions** — conversations maintain context across messages
- **Session management** — create, delete, switch, list, and share sessions
- **Model switching** — change AI models on the fly (`/model`)
- **Plan/Build modes** — toggle between read-only analysis and full execution
- **Smart formatting** — code blocks with syntax highlighting in Telegram
- **Auto message splitting** — handles responses longer than Telegram's 4096 char limit
- **Security** — whitelist-based access control + rate limiting
- **Workspace Switching** — Switching from one workspace to another
- **Uploading from Mobile to WorkSpace** - U can upload the documents/images from your mobile to the opencode agent workspace
- **Workspace Management** — Creation and deletion of the workspace/folder

## 📋 Prerequisites

1. **Python 3.10+**
2. **OpenCode CLI** — install via:
   ```bash
   npm install -g opencode-ai
   # or
   curl -fsSL https://opencode.ai/install | bash
   ```
3. **Telegram Bot Token** — get one from [@BotFather](https://t.me/BotFather)
4. **Your Telegram User ID** — send `/id` to the bot after setup, or use [@userinfobot](https://t.me/userinfobot)

### Quick Installation:
```bash
pip install telegram-opencode-bridge-bot==0.1.6
telegram-opencode-bot
telegram-opencode-bot --env (use --env flag if u want to re-configure later anytime)
```
### Manuall Installation:
### 1. Clone & Install

```bash
cd telegram-opencode-bot
pip install -r requirements.txt
```

### 2. Run the Bot

```bash
python bot.py
python bot.py --env (use --env flag if u want to re-configure later anytime)
```
> **💡 Tip:** Don't know your Telegram user ID? Start the bot with `AUTHORIZED_USERS=0` temporarily, send `/id` to the bot, then update the `.env` with your real ID.

### 3. Chat!

Open Telegram, find your bot, and start asking! 🎉

## 📱 Commands

| Command | Description |
|---------|-------------|
| `/start` | Welcome message & connection check |
| `/help` | Show all commands |
| `/new` | Start a fresh conversation |
| `/sessions` | List your recent sessions/conversations and to select a session/conversation |
| `/plan` | plan mode |
| `/build` | build mode |
| `/share` | Share current session/conversation (public URL) |
| `/status` | Check connection & session details |
| `/id` | Show your Telegram user ID |
| `/stop` | Abort active model processing |
| `/models` | List all available providers, models and to select the model |
| `/project` | To view the current workspace, sub folder workspaces and to change the workspace |
| `/enable` | To enable the streaming |
| `/disable` | To disable the streaming |
| `/create_project` | To create new project/folder/workspace |
| `/delete_project` | To create new project/folder/workspace |
| `/delete` | To delete a conversation |

## 🏗️ Architecture

```
Telegram User
    │
    ▼
Telegram Bot (Python)
    │
    ├──► OpenCode HTTP API (localhost:4096)  ← primary
            │
            ├──► LLM Provider (Claude/GPT/Gemini)
            └──► Local Filesystem & Shell
```

## ⚙️ Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | **Required** |
| `AUTHORIZED_USERS` | Comma-separated Telegram user IDs | **Required** |
| `OPENCODE_SERVER_URL` | OpenCode HTTP API URL | `http://localhost:4096` |
| `OPENCODE_SERVER_USERNAME` | OpenCode auth username | *(empty)* |
| `OPENCODE_SERVER_PASSWORD` | OpenCode auth password | *(empty)* |
| `OPENCODE_MODEL` | Default AI model | `anthropic/claude-sonnet-4` |
| `OPENCODE_WORK_DIR` | Working directory for OpenCode | `.` |
| `MAX_MESSAGE_LENGTH` | Max Telegram message length | `4000` |
| `RESPONSE_TIMEOUT` | Max wait for response (seconds) | `0` |
| `DB_PATH` | SQLite database path | `sessions.db` |

## 🔒 Security

- **User whitelist** — only Telegram user IDs in `AUTHORIZED_USERS` can use the bot
- **Rate limiting** — 20 requests per minute per user (configurable)
- **No public exposure** — designed to run on your local machine

> ⚠️ **Warning:** This bot executes AI-driven code on your machine. Only authorize trusted users.

## 📁 Project Structure

```
telegram-opencode-bot/
├── bot.py                  # Main entry point
├── config.py               # Environment configuration
├── handlers/
│   ├── commands.py         # Slash command handlers
│   └── messages.py         # Text message → OpenCode bridge
├── opencode/
│   ├── client.py           # OpenCode HTTP API client
│   
├── sessions/
│   └── manager.py          # Per-user session tracking (SQLite)
├── utils/
│   ├── formatting.py       # Telegram message formatting
│   └── security.py         # Auth, rate limiting, sanitization
├── .env.example            # Environment template
├── requirements.txt        # Python dependencies
└── README.md               # This file
```

