telegram-opencode-bridge-bot 0.1.0__tar.gz → 0.1.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/.env.example +17 -17
  2. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/MANIFEST.in +2 -2
  3. {telegram_opencode_bridge_bot-0.1.0/telegram_opencode_bridge_bot.egg-info → telegram_opencode_bridge_bot-0.1.3}/PKG-INFO +151 -156
  4. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/README.md +134 -139
  5. telegram_opencode_bridge_bot-0.1.3/bot.py +448 -0
  6. telegram_opencode_bridge_bot-0.1.3/config.py +92 -0
  7. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/handlers/commands.py +943 -943
  8. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/handlers/messages.py +482 -482
  9. telegram_opencode_bridge_bot-0.1.3/list_session_models.py +44 -0
  10. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/opencode/client.py +443 -443
  11. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/opencode/server.py +144 -144
  12. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/pyproject.toml +38 -35
  13. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/sessions/manager.py +342 -342
  14. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/setup.cfg +4 -4
  15. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3/telegram_opencode_bridge_bot.egg-info}/PKG-INFO +151 -156
  16. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/telegram_opencode_bridge_bot.egg-info/SOURCES.txt +3 -0
  17. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/telegram_opencode_bridge_bot.egg-info/top_level.txt +3 -0
  18. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/utils/formatting.py +218 -218
  19. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/handlers/__init__.py +0 -0
  20. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/opencode/__init__.py +0 -0
  21. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/requirements.txt +0 -0
  22. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/sessions/__init__.py +0 -0
  23. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/telegram_opencode_bridge_bot.egg-info/dependency_links.txt +0 -0
  24. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/telegram_opencode_bridge_bot.egg-info/entry_points.txt +0 -0
  25. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/telegram_opencode_bridge_bot.egg-info/requires.txt +0 -0
  26. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/utils/__init__.py +0 -0
  27. {telegram_opencode_bridge_bot-0.1.0 → telegram_opencode_bridge_bot-0.1.3}/utils/security.py +0 -0
@@ -1,17 +1,17 @@
1
- # Telegram Bot Configuration
2
- TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
3
- AUTHORIZED_USERS=123456789,987654321
4
-
5
- # OpenCode Configuration
6
- OPENCODE_SERVER_URL=http://localhost:4096
7
- OPENCODE_SERVER_USERNAME=
8
- OPENCODE_SERVER_PASSWORD=
9
- OPENCODE_MODEL=anthropic/claude-sonnet-4
10
- OPENCODE_WORK_DIR=.
11
-
12
- # Limits
13
- MAX_MESSAGE_LENGTH=4000
14
- RESPONSE_TIMEOUT=0 # Set to 0 to disable request timeouts entirely
15
-
16
- # Database
17
- DB_PATH=sessions.db
1
+ # Telegram Bot Configuration
2
+ TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
3
+ AUTHORIZED_USERS=123456789,987654321
4
+
5
+ # OpenCode Configuration
6
+ OPENCODE_SERVER_URL=http://localhost:4096
7
+ OPENCODE_SERVER_USERNAME=
8
+ OPENCODE_SERVER_PASSWORD=
9
+ OPENCODE_MODEL=opencode/deepseek-v4-flash-free
10
+ OPENCODE_WORK_DIR=.
11
+
12
+ # Limits
13
+ MAX_MESSAGE_LENGTH=4000
14
+ RESPONSE_TIMEOUT=0 # Set to 0 to disable request timeouts entirely
15
+
16
+ # Database
17
+ DB_PATH=sessions.db
@@ -1,3 +1,3 @@
1
- include .env.example
2
- include README.md
1
+ include .env.example
2
+ include README.md
3
3
  include requirements.txt
@@ -1,156 +1,151 @@
1
- Metadata-Version: 2.4
2
- Name: telegram-opencode-bridge-bot
3
- Version: 0.1.0
4
- Summary: A Telegram bot that bridges messages directly to OpenCode — an AI coding agent running on your machine
5
- Author-email: MaheshNagabhairava <your@email.com>
6
- License-Expression: MIT
7
- Project-URL: Homepage, https://github.com/MaheshNagabhairava/telegram-opencode-bridge-bot
8
- Keywords: telegram,bot,opencode,ai,coding,bridge
9
- Classifier: Programming Language :: Python :: 3
10
- Classifier: Operating System :: OS Independent
11
- Requires-Python: >=3.10
12
- Description-Content-Type: text/markdown
13
- Requires-Dist: python-telegram-bot[ext]>=21.0
14
- Requires-Dist: aiohttp>=3.9.0
15
- Requires-Dist: python-dotenv>=1.0.0
16
- Requires-Dist: aiosqlite>=0.19.0
17
-
18
- # 🤖 Telegram → OpenCode Bridge Bot
19
-
20
- 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.
21
-
22
- ## ✨ Features
23
-
24
- - **Direct OpenCode integration** — routes your messages to OpenCode's HTTP API
25
- - **Persistent sessions** — conversations maintain context across messages
26
- - **Session management** — create, switch, list, and share sessions
27
- - **Model switching** — change AI models on the fly (`/model`)
28
- - **Plan/Build modes** — toggle between read-only analysis and full execution
29
- - **Smart formatting** — code blocks with syntax highlighting in Telegram
30
- - **Auto message splitting** — handles responses longer than Telegram's 4096 char limit
31
- - **Security** — whitelist-based access control + rate limiting
32
- - **Workspace Switching** — Switching from one workspace to another
33
-
34
- ## 📋 Prerequisites
35
-
36
- 1. **Python 3.10+**
37
- 2. **OpenCode CLI** — install via:
38
- ```bash
39
- npm install -g opencode-ai
40
- # or
41
- curl -fsSL https://opencode.ai/install | bash
42
- ```
43
- 3. **Telegram Bot Token** — get one from [@BotFather](https://t.me/BotFather)
44
- 4. **Your Telegram User ID** — send `/id` to the bot after setup, or use [@userinfobot](https://t.me/userinfobot)
45
-
46
- ## 🚀 Quick Start
47
-
48
- ### 1. Clone & Install
49
-
50
- ```bash
51
- cd telegram-opencode-bot
52
- pip install -r requirements.txt
53
- ```
54
-
55
- ### 2. Start OpenCode Server
56
-
57
- In a separate terminal:
58
-
59
- ```bash
60
- opencode serve --port 4096 --hostname 127.0.0.1
61
- ```
62
-
63
- This starts the OpenCode HTTP API on `localhost:4096`.
64
-
65
- ### 3. Run the Bot
66
-
67
- ```bash
68
- python bot.py
69
- python bot.py --env (if u want to setup ur configuration later)
70
- ```
71
- > **💡 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.
72
-
73
- ### 4. Chat!
74
-
75
- Open Telegram, find your bot, and start asking! 🎉
76
-
77
- ## 📱 Commands
78
-
79
- | Command | Description |
80
- |---------|-------------|
81
- | `/start` | Welcome message & connection check |
82
- | `/help` | Show all commands |
83
- | `/new` | Start a fresh conversation |
84
- | `/sessions` | List your recent sessions |
85
- | `/switch <id>` | Switch to a different session |
86
- | `/model <name>` | Change AI model(ex: /model opencode/deepseek-v4-flash-free) |
87
- | `/mode <plan\|build>` | Toggle plan/build mode |
88
- | `/share` | Share current session (public URL) |
89
- | `/status` | Check connection & session details |
90
- | `/id` | Show your Telegram user ID |
91
- | `/stop` | Abort active model processing |
92
- | `/models` | List all available models |
93
- | `/project` | To view the current workspace, sub folder workspaces and to change the workspace (ex: /project 2)|
94
- | `/project depth <1to5>` | Depth level recursive check for subfolders (ex: if u give depth 2, only 2 sub folders it will show from root) |
95
- | `/enable` | To enable the streaming |
96
- | `/disable` | To disable the streaming |
97
-
98
- ## 🏗️ Architecture
99
-
100
- ```
101
- Telegram User
102
-
103
-
104
- Telegram Bot (Python)
105
-
106
- ├──► OpenCode HTTP API (localhost:4096) ← primary
107
-
108
- ├──► LLM Provider (Claude/GPT/Gemini)
109
- └──► Local Filesystem & Shell
110
- ```
111
-
112
- ## ⚙️ Configuration
113
-
114
- | Variable | Description | Default |
115
- |----------|-------------|---------|
116
- | `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | **Required** |
117
- | `AUTHORIZED_USERS` | Comma-separated Telegram user IDs | **Required** |
118
- | `OPENCODE_SERVER_URL` | OpenCode HTTP API URL | `http://localhost:4096` |
119
- | `OPENCODE_SERVER_USERNAME` | OpenCode auth username | *(empty)* |
120
- | `OPENCODE_SERVER_PASSWORD` | OpenCode auth password | *(empty)* |
121
- | `OPENCODE_MODEL` | Default AI model | `anthropic/claude-sonnet-4` |
122
- | `OPENCODE_WORK_DIR` | Working directory for OpenCode | `.` |
123
- | `MAX_MESSAGE_LENGTH` | Max Telegram message length | `4000` |
124
- | `RESPONSE_TIMEOUT` | Max wait for response (seconds) | `0` |
125
- | `DB_PATH` | SQLite database path | `sessions.db` |
126
-
127
- ## 🔒 Security
128
-
129
- - **User whitelist** — only Telegram user IDs in `AUTHORIZED_USERS` can use the bot
130
- - **Rate limiting** — 20 requests per minute per user (configurable)
131
- - **No public exposure** — designed to run on your local machine
132
-
133
- > ⚠️ **Warning:** This bot executes AI-driven code on your machine. Only authorize trusted users.
134
-
135
- ## 📁 Project Structure
136
-
137
- ```
138
- telegram-opencode-bot/
139
- ├── bot.py # Main entry point
140
- ├── config.py # Environment configuration
141
- ├── handlers/
142
- ├── commands.py # Slash command handlers
143
- │ └── messages.py # Text message OpenCode bridge
144
- ├── opencode/
145
- │ ├── client.py # OpenCode HTTP API client
146
-
147
- ├── sessions/
148
- │ └── manager.py # Per-user session tracking (SQLite)
149
- ├── utils/
150
- │ ├── formatting.py # Telegram message formatting
151
- │ └── security.py # Auth, rate limiting, sanitization
152
- ├── .env.example # Environment template
153
- ├── requirements.txt # Python dependencies
154
- └── README.md # This file
155
- ```
156
-
1
+ Metadata-Version: 2.4
2
+ Name: telegram-opencode-bridge-bot
3
+ Version: 0.1.3
4
+ Summary: A Telegram bot that bridges messages directly to OpenCode — an AI coding agent running on your machine
5
+ Author-email: MaheshNagabhairava <maheshnagabhirava12345@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/MaheshNagabhairava/telegram-opencode-bridge-bot
8
+ Keywords: telegram,bot,opencode,ai,coding,bridge
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Requires-Python: >=3.10
12
+ Description-Content-Type: text/markdown
13
+ Requires-Dist: python-telegram-bot[ext]>=21.0
14
+ Requires-Dist: aiohttp>=3.9.0
15
+ Requires-Dist: python-dotenv>=1.0.0
16
+ Requires-Dist: aiosqlite>=0.19.0
17
+
18
+ # 🤖 Telegram → OpenCode Bridge Bot
19
+
20
+ 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.
21
+
22
+ ## ✨ Features
23
+
24
+ - **Direct OpenCode integration** — routes your messages to OpenCode's HTTP API
25
+ - **Persistent sessions** — conversations maintain context across messages
26
+ - **Session management** — create, switch, list, and share sessions
27
+ - **Model switching** — change AI models on the fly (`/model`)
28
+ - **Plan/Build modes** — toggle between read-only analysis and full execution
29
+ - **Smart formatting** — code blocks with syntax highlighting in Telegram
30
+ - **Auto message splitting** — handles responses longer than Telegram's 4096 char limit
31
+ - **Security** — whitelist-based access control + rate limiting
32
+ - **Workspace Switching** — Switching from one workspace to another
33
+
34
+ ## 📋 Prerequisites
35
+
36
+ 1. **Python 3.10+**
37
+ 2. **OpenCode CLI** — install via:
38
+ ```bash
39
+ npm install -g opencode-ai
40
+ # or
41
+ curl -fsSL https://opencode.ai/install | bash
42
+ ```
43
+ 3. **Telegram Bot Token** — get one from [@BotFather](https://t.me/BotFather)
44
+ 4. **Your Telegram User ID** — send `/id` to the bot after setup, or use [@userinfobot](https://t.me/userinfobot)
45
+
46
+ ### Quick Installation:
47
+ ```bash
48
+ pip install telegram-opencode-bridge-bot==0.1.2
49
+ telegram-opencode-bot
50
+ telegram-opencode-bot --env (use --env flag if u want to re-configure later anytime)
51
+ ```
52
+ ### Manuall Installation:
53
+ ### 1. Clone & Install
54
+
55
+ ```bash
56
+ cd telegram-opencode-bot
57
+ pip install -r requirements.txt
58
+ ```
59
+
60
+ ### 2. Run the Bot
61
+
62
+ ```bash
63
+ python bot.py
64
+ python bot.py --env (use --env flag if u want to re-configure later anytime)
65
+ ```
66
+ > **💡 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.
67
+
68
+ ### 3. Chat!
69
+
70
+ Open Telegram, find your bot, and start asking! 🎉
71
+
72
+ ## 📱 Commands
73
+
74
+ | Command | Description |
75
+ |---------|-------------|
76
+ | `/start` | Welcome message & connection check |
77
+ | `/help` | Show all commands |
78
+ | `/new` | Start a fresh conversation |
79
+ | `/sessions` | List your recent sessions |
80
+ | `/switch <id>` | Switch to a different session |
81
+ | `/model <name>` | Change AI model(ex: /model opencode/deepseek-v4-flash-free) |
82
+ | `/mode <plan\|build>` | Toggle plan/build mode |
83
+ | `/share` | Share current session (public URL) |
84
+ | `/status` | Check connection & session details |
85
+ | `/id` | Show your Telegram user ID |
86
+ | `/stop` | Abort active model processing |
87
+ | `/models` | List all available models |
88
+ | `/project` | To view the current workspace, sub folder workspaces and to change the workspace (ex: /project 2)|
89
+ | `/project depth <1to5>` | Depth level recursive check for subfolders (ex: if u give depth 2, only 2 sub folders it will show from root) |
90
+ | `/enable` | To enable the streaming |
91
+ | `/disable` | To disable the streaming |
92
+
93
+ ## 🏗️ Architecture
94
+
95
+ ```
96
+ Telegram User
97
+
98
+
99
+ Telegram Bot (Python)
100
+
101
+ ├──► OpenCode HTTP API (localhost:4096) ← primary
102
+
103
+ ├──► LLM Provider (Claude/GPT/Gemini)
104
+ └──► Local Filesystem & Shell
105
+ ```
106
+
107
+ ## ⚙️ Configuration
108
+
109
+ | Variable | Description | Default |
110
+ |----------|-------------|---------|
111
+ | `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | **Required** |
112
+ | `AUTHORIZED_USERS` | Comma-separated Telegram user IDs | **Required** |
113
+ | `OPENCODE_SERVER_URL` | OpenCode HTTP API URL | `http://localhost:4096` |
114
+ | `OPENCODE_SERVER_USERNAME` | OpenCode auth username | *(empty)* |
115
+ | `OPENCODE_SERVER_PASSWORD` | OpenCode auth password | *(empty)* |
116
+ | `OPENCODE_MODEL` | Default AI model | `anthropic/claude-sonnet-4` |
117
+ | `OPENCODE_WORK_DIR` | Working directory for OpenCode | `.` |
118
+ | `MAX_MESSAGE_LENGTH` | Max Telegram message length | `4000` |
119
+ | `RESPONSE_TIMEOUT` | Max wait for response (seconds) | `0` |
120
+ | `DB_PATH` | SQLite database path | `sessions.db` |
121
+
122
+ ## 🔒 Security
123
+
124
+ - **User whitelist** only Telegram user IDs in `AUTHORIZED_USERS` can use the bot
125
+ - **Rate limiting** 20 requests per minute per user (configurable)
126
+ - **No public exposure** — designed to run on your local machine
127
+
128
+ > ⚠️ **Warning:** This bot executes AI-driven code on your machine. Only authorize trusted users.
129
+
130
+ ## 📁 Project Structure
131
+
132
+ ```
133
+ telegram-opencode-bot/
134
+ ├── bot.py # Main entry point
135
+ ├── config.py # Environment configuration
136
+ ├── handlers/
137
+ │ ├── commands.py # Slash command handlers
138
+ │ └── messages.py # Text message → OpenCode bridge
139
+ ├── opencode/
140
+ ├── client.py # OpenCode HTTP API client
141
+
142
+ ├── sessions/
143
+ │ └── manager.py # Per-user session tracking (SQLite)
144
+ ├── utils/
145
+ │ ├── formatting.py # Telegram message formatting
146
+ └── security.py # Auth, rate limiting, sanitization
147
+ ├── .env.example # Environment template
148
+ ├── requirements.txt # Python dependencies
149
+ └── README.md # This file
150
+ ```
151
+
@@ -1,139 +1,134 @@
1
- # 🤖 Telegram → OpenCode Bridge Bot
2
-
3
- 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.
4
-
5
- ## ✨ Features
6
-
7
- - **Direct OpenCode integration** — routes your messages to OpenCode's HTTP API
8
- - **Persistent sessions** — conversations maintain context across messages
9
- - **Session management** — create, switch, list, and share sessions
10
- - **Model switching** — change AI models on the fly (`/model`)
11
- - **Plan/Build modes** — toggle between read-only analysis and full execution
12
- - **Smart formatting** — code blocks with syntax highlighting in Telegram
13
- - **Auto message splitting** — handles responses longer than Telegram's 4096 char limit
14
- - **Security** — whitelist-based access control + rate limiting
15
- - **Workspace Switching** — Switching from one workspace to another
16
-
17
- ## 📋 Prerequisites
18
-
19
- 1. **Python 3.10+**
20
- 2. **OpenCode CLI** — install via:
21
- ```bash
22
- npm install -g opencode-ai
23
- # or
24
- curl -fsSL https://opencode.ai/install | bash
25
- ```
26
- 3. **Telegram Bot Token** — get one from [@BotFather](https://t.me/BotFather)
27
- 4. **Your Telegram User ID** — send `/id` to the bot after setup, or use [@userinfobot](https://t.me/userinfobot)
28
-
29
- ## 🚀 Quick Start
30
-
31
- ### 1. Clone & Install
32
-
33
- ```bash
34
- cd telegram-opencode-bot
35
- pip install -r requirements.txt
36
- ```
37
-
38
- ### 2. Start OpenCode Server
39
-
40
- In a separate terminal:
41
-
42
- ```bash
43
- opencode serve --port 4096 --hostname 127.0.0.1
44
- ```
45
-
46
- This starts the OpenCode HTTP API on `localhost:4096`.
47
-
48
- ### 3. Run the Bot
49
-
50
- ```bash
51
- python bot.py
52
- python bot.py --env (if u want to setup ur configuration later)
53
- ```
54
- > **💡 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.
55
-
56
- ### 4. Chat!
57
-
58
- Open Telegram, find your bot, and start asking! 🎉
59
-
60
- ## 📱 Commands
61
-
62
- | Command | Description |
63
- |---------|-------------|
64
- | `/start` | Welcome message & connection check |
65
- | `/help` | Show all commands |
66
- | `/new` | Start a fresh conversation |
67
- | `/sessions` | List your recent sessions |
68
- | `/switch <id>` | Switch to a different session |
69
- | `/model <name>` | Change AI model(ex: /model opencode/deepseek-v4-flash-free) |
70
- | `/mode <plan\|build>` | Toggle plan/build mode |
71
- | `/share` | Share current session (public URL) |
72
- | `/status` | Check connection & session details |
73
- | `/id` | Show your Telegram user ID |
74
- | `/stop` | Abort active model processing |
75
- | `/models` | List all available models |
76
- | `/project` | To view the current workspace, sub folder workspaces and to change the workspace (ex: /project 2)|
77
- | `/project depth <1to5>` | Depth level recursive check for subfolders (ex: if u give depth 2, only 2 sub folders it will show from root) |
78
- | `/enable` | To enable the streaming |
79
- | `/disable` | To disable the streaming |
80
-
81
- ## 🏗️ Architecture
82
-
83
- ```
84
- Telegram User
85
-
86
-
87
- Telegram Bot (Python)
88
-
89
- ├──► OpenCode HTTP API (localhost:4096) ← primary
90
-
91
- ├──► LLM Provider (Claude/GPT/Gemini)
92
- └──► Local Filesystem & Shell
93
- ```
94
-
95
- ## ⚙️ Configuration
96
-
97
- | Variable | Description | Default |
98
- |----------|-------------|---------|
99
- | `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | **Required** |
100
- | `AUTHORIZED_USERS` | Comma-separated Telegram user IDs | **Required** |
101
- | `OPENCODE_SERVER_URL` | OpenCode HTTP API URL | `http://localhost:4096` |
102
- | `OPENCODE_SERVER_USERNAME` | OpenCode auth username | *(empty)* |
103
- | `OPENCODE_SERVER_PASSWORD` | OpenCode auth password | *(empty)* |
104
- | `OPENCODE_MODEL` | Default AI model | `anthropic/claude-sonnet-4` |
105
- | `OPENCODE_WORK_DIR` | Working directory for OpenCode | `.` |
106
- | `MAX_MESSAGE_LENGTH` | Max Telegram message length | `4000` |
107
- | `RESPONSE_TIMEOUT` | Max wait for response (seconds) | `0` |
108
- | `DB_PATH` | SQLite database path | `sessions.db` |
109
-
110
- ## 🔒 Security
111
-
112
- - **User whitelist** — only Telegram user IDs in `AUTHORIZED_USERS` can use the bot
113
- - **Rate limiting** — 20 requests per minute per user (configurable)
114
- - **No public exposure** — designed to run on your local machine
115
-
116
- > ⚠️ **Warning:** This bot executes AI-driven code on your machine. Only authorize trusted users.
117
-
118
- ## 📁 Project Structure
119
-
120
- ```
121
- telegram-opencode-bot/
122
- ├── bot.py # Main entry point
123
- ├── config.py # Environment configuration
124
- ├── handlers/
125
- ├── commands.py # Slash command handlers
126
- │ └── messages.py # Text message OpenCode bridge
127
- ├── opencode/
128
- │ ├── client.py # OpenCode HTTP API client
129
-
130
- ├── sessions/
131
- │ └── manager.py # Per-user session tracking (SQLite)
132
- ├── utils/
133
- │ ├── formatting.py # Telegram message formatting
134
- │ └── security.py # Auth, rate limiting, sanitization
135
- ├── .env.example # Environment template
136
- ├── requirements.txt # Python dependencies
137
- └── README.md # This file
138
- ```
139
-
1
+ # 🤖 Telegram → OpenCode Bridge Bot
2
+
3
+ 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.
4
+
5
+ ## ✨ Features
6
+
7
+ - **Direct OpenCode integration** — routes your messages to OpenCode's HTTP API
8
+ - **Persistent sessions** — conversations maintain context across messages
9
+ - **Session management** — create, switch, list, and share sessions
10
+ - **Model switching** — change AI models on the fly (`/model`)
11
+ - **Plan/Build modes** — toggle between read-only analysis and full execution
12
+ - **Smart formatting** — code blocks with syntax highlighting in Telegram
13
+ - **Auto message splitting** — handles responses longer than Telegram's 4096 char limit
14
+ - **Security** — whitelist-based access control + rate limiting
15
+ - **Workspace Switching** — Switching from one workspace to another
16
+
17
+ ## 📋 Prerequisites
18
+
19
+ 1. **Python 3.10+**
20
+ 2. **OpenCode CLI** — install via:
21
+ ```bash
22
+ npm install -g opencode-ai
23
+ # or
24
+ curl -fsSL https://opencode.ai/install | bash
25
+ ```
26
+ 3. **Telegram Bot Token** — get one from [@BotFather](https://t.me/BotFather)
27
+ 4. **Your Telegram User ID** — send `/id` to the bot after setup, or use [@userinfobot](https://t.me/userinfobot)
28
+
29
+ ### Quick Installation:
30
+ ```bash
31
+ pip install telegram-opencode-bridge-bot==0.1.2
32
+ telegram-opencode-bot
33
+ telegram-opencode-bot --env (use --env flag if u want to re-configure later anytime)
34
+ ```
35
+ ### Manuall Installation:
36
+ ### 1. Clone & Install
37
+
38
+ ```bash
39
+ cd telegram-opencode-bot
40
+ pip install -r requirements.txt
41
+ ```
42
+
43
+ ### 2. Run the Bot
44
+
45
+ ```bash
46
+ python bot.py
47
+ python bot.py --env (use --env flag if u want to re-configure later anytime)
48
+ ```
49
+ > **💡 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.
50
+
51
+ ### 3. Chat!
52
+
53
+ Open Telegram, find your bot, and start asking! 🎉
54
+
55
+ ## 📱 Commands
56
+
57
+ | Command | Description |
58
+ |---------|-------------|
59
+ | `/start` | Welcome message & connection check |
60
+ | `/help` | Show all commands |
61
+ | `/new` | Start a fresh conversation |
62
+ | `/sessions` | List your recent sessions |
63
+ | `/switch <id>` | Switch to a different session |
64
+ | `/model <name>` | Change AI model(ex: /model opencode/deepseek-v4-flash-free) |
65
+ | `/mode <plan\|build>` | Toggle plan/build mode |
66
+ | `/share` | Share current session (public URL) |
67
+ | `/status` | Check connection & session details |
68
+ | `/id` | Show your Telegram user ID |
69
+ | `/stop` | Abort active model processing |
70
+ | `/models` | List all available models |
71
+ | `/project` | To view the current workspace, sub folder workspaces and to change the workspace (ex: /project 2)|
72
+ | `/project depth <1to5>` | Depth level recursive check for subfolders (ex: if u give depth 2, only 2 sub folders it will show from root) |
73
+ | `/enable` | To enable the streaming |
74
+ | `/disable` | To disable the streaming |
75
+
76
+ ## 🏗️ Architecture
77
+
78
+ ```
79
+ Telegram User
80
+
81
+
82
+ Telegram Bot (Python)
83
+
84
+ ├──► OpenCode HTTP API (localhost:4096) ← primary
85
+
86
+ ├──► LLM Provider (Claude/GPT/Gemini)
87
+ └──► Local Filesystem & Shell
88
+ ```
89
+
90
+ ## ⚙️ Configuration
91
+
92
+ | Variable | Description | Default |
93
+ |----------|-------------|---------|
94
+ | `TELEGRAM_BOT_TOKEN` | Bot token from @BotFather | **Required** |
95
+ | `AUTHORIZED_USERS` | Comma-separated Telegram user IDs | **Required** |
96
+ | `OPENCODE_SERVER_URL` | OpenCode HTTP API URL | `http://localhost:4096` |
97
+ | `OPENCODE_SERVER_USERNAME` | OpenCode auth username | *(empty)* |
98
+ | `OPENCODE_SERVER_PASSWORD` | OpenCode auth password | *(empty)* |
99
+ | `OPENCODE_MODEL` | Default AI model | `anthropic/claude-sonnet-4` |
100
+ | `OPENCODE_WORK_DIR` | Working directory for OpenCode | `.` |
101
+ | `MAX_MESSAGE_LENGTH` | Max Telegram message length | `4000` |
102
+ | `RESPONSE_TIMEOUT` | Max wait for response (seconds) | `0` |
103
+ | `DB_PATH` | SQLite database path | `sessions.db` |
104
+
105
+ ## 🔒 Security
106
+
107
+ - **User whitelist** only Telegram user IDs in `AUTHORIZED_USERS` can use the bot
108
+ - **Rate limiting** 20 requests per minute per user (configurable)
109
+ - **No public exposure** — designed to run on your local machine
110
+
111
+ > ⚠️ **Warning:** This bot executes AI-driven code on your machine. Only authorize trusted users.
112
+
113
+ ## 📁 Project Structure
114
+
115
+ ```
116
+ telegram-opencode-bot/
117
+ ├── bot.py # Main entry point
118
+ ├── config.py # Environment configuration
119
+ ├── handlers/
120
+ │ ├── commands.py # Slash command handlers
121
+ │ └── messages.py # Text message → OpenCode bridge
122
+ ├── opencode/
123
+ ├── client.py # OpenCode HTTP API client
124
+
125
+ ├── sessions/
126
+ │ └── manager.py # Per-user session tracking (SQLite)
127
+ ├── utils/
128
+ │ ├── formatting.py # Telegram message formatting
129
+ └── security.py # Auth, rate limiting, sanitization
130
+ ├── .env.example # Environment template
131
+ ├── requirements.txt # Python dependencies
132
+ └── README.md # This file
133
+ ```
134
+