opencode-telegram-connect 1.0.0 → 1.0.1
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.
- package/LICENSE +1 -1
- package/README.md +183 -105
- package/package.json +16 -2
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,87 +1,136 @@
|
|
|
1
|
-
|
|
1
|
+
# OpenCode Telegram Connect
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Control a running OpenCode session from Telegram with your own bot. Messages are forwarded to OpenCode; answers, permission requests, and questions from the agent appear in Telegram. The plugin supports OpenCode on Windows, WSL, Linux, and macOS.
|
|
4
4
|
|
|
5
|
-
**Telegram
|
|
5
|
+
**Telegram stays off when OpenCode starts.** The connection only begins when you ask your agent to connect and it calls `telegram_connect`. There is no Telegram command to turn it on; the former start command is ignored and never forwarded to the model.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Features
|
|
8
8
|
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
9
|
+
- **Agent-gated connection.** `telegram_connect` validates the token, acquires a single-instance poll lock, and starts long polling. `telegram_disconnect` stops it; `telegram_status` reports the state.
|
|
10
|
+
- **Allowlist security.** Only configured Telegram user IDs or chat IDs can control the session; everything else is rejected. One-time pairing codes are supported when no allowlist is configured.
|
|
11
|
+
- **Full session control.** List, switch, create, and rename sessions; list and switch models; abort running work.
|
|
12
|
+
- **Permissions and questions in chat.** Approve, always-allow, or deny tool permissions and answer agent questions directly from Telegram, including inline buttons.
|
|
13
|
+
- **Local credentials only.** The bot token and your user ID live in a local env file; nothing is uploaded anywhere.
|
|
13
14
|
|
|
14
|
-
|
|
15
|
+
## System requirements
|
|
15
16
|
|
|
16
|
-
|
|
17
|
+
### Runtime requirements
|
|
17
18
|
|
|
18
|
-
|
|
19
|
+
- OpenCode 1.18.0 or newer with npm plugin support (tested with OpenCode 1.18.29).
|
|
20
|
+
- A working model configuration in OpenCode.
|
|
21
|
+
- Node.js 20 or newer (the runtime is provided by OpenCode; also needed for the helper command below).
|
|
22
|
+
- Telegram on your phone or computer and internet access on the OpenCode machine.
|
|
19
23
|
|
|
20
|
-
|
|
21
|
-
- Linux/macOS: `~/.config/opencode/opencode.json`
|
|
24
|
+
OpenCode must be running while you use Telegram. The plugin does not start a separate OpenCode server and opens no inbound port.
|
|
22
25
|
|
|
23
|
-
|
|
26
|
+
### Development/build requirements
|
|
27
|
+
|
|
28
|
+
These are required only when building or testing this repository from source:
|
|
29
|
+
|
|
30
|
+
- Node.js 20 or newer.
|
|
31
|
+
- npm.
|
|
32
|
+
|
|
33
|
+
## Platform support
|
|
34
|
+
|
|
35
|
+
The plugin uses only Node.js built-ins (`node:fs`, `node:os`, `node:path`, `node:http`) and the OpenCode plugin/SDK API. There is no platform-specific code:
|
|
36
|
+
|
|
37
|
+
- The Telegram transport is plain HTTPS long polling, identical on Windows, WSL, Linux, and macOS.
|
|
38
|
+
- The config file is resolved through `os.homedir()` (`~/.config/opencode/telegram.env`), so it is correct on every platform.
|
|
39
|
+
- The bot poll lock lives under the per-user config directory and works on all supported platforms.
|
|
40
|
+
|
|
41
|
+
## Install in native Windows OpenCode
|
|
42
|
+
|
|
43
|
+
Open PowerShell and add the package to the `plugin` array of your global config (`%USERPROFILE%\.config\opencode\opencode.json`):
|
|
44
|
+
|
|
45
|
+
```powershell
|
|
46
|
+
opencode --version
|
|
47
|
+
notepad "$env:USERPROFILE\.config\opencode\opencode.json"
|
|
48
|
+
```
|
|
24
49
|
|
|
25
50
|
```json
|
|
26
51
|
{
|
|
27
52
|
"$schema": "https://opencode.ai/config.json",
|
|
28
|
-
"plugin": ["opencode-telegram-connect@1.0.
|
|
53
|
+
"plugin": ["opencode-telegram-connect@1.0.1"]
|
|
29
54
|
}
|
|
30
55
|
```
|
|
31
56
|
|
|
32
|
-
OpenCode
|
|
57
|
+
Keep any other settings and plugins in the file. OpenCode downloads and installs the npm package automatically on the next start. A global npm installation alone does not activate the plugin. Remove old entries of this plugin and any local `file://` references so it is loaded only once.
|
|
33
58
|
|
|
34
|
-
|
|
59
|
+
Optionally install the package globally to get the `opencode-telegram-user-id` helper command:
|
|
35
60
|
|
|
36
|
-
```
|
|
37
|
-
npm install -g opencode-telegram-connect@1.0.
|
|
61
|
+
```powershell
|
|
62
|
+
npm install -g opencode-telegram-connect@1.0.1
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
See also the [OpenCode plugin documentation](https://opencode.ai/docs/plugins/).
|
|
66
|
+
|
|
67
|
+
## Install in OpenCode running in WSL or Linux
|
|
68
|
+
|
|
69
|
+
Add the same entry to `~/.config/opencode/opencode.json`:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
opencode --version
|
|
73
|
+
nano ~/.config/opencode/opencode.json
|
|
74
|
+
opencode
|
|
38
75
|
```
|
|
39
76
|
|
|
40
|
-
|
|
77
|
+
If your global config is `opencode.jsonc`, that file takes precedence - add the entry to its `plugin` array and check the effective list with `opencode debug config`. Pinning a version (e.g. `opencode-telegram-connect@1.0.1`) is recommended; the bare `latest` spec is cached permanently on first install.
|
|
78
|
+
|
|
79
|
+
## Uninstall
|
|
80
|
+
|
|
81
|
+
OpenCode has no plugin removal command, so uninstalling is a manual three-step process:
|
|
82
|
+
|
|
83
|
+
1. Remove the `"opencode-telegram-connect"` entry from the `plugin` array of your global config (`~/.config/opencode/opencode.jsonc` or `~/.config/opencode/opencode.json`).
|
|
84
|
+
2. Delete the plugin cache:
|
|
85
|
+
- Windows PowerShell: `Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\opencode\packages\opencode-telegram-connect*"`
|
|
86
|
+
- WSL/Linux/macOS: `rm -rf ~/.cache/opencode/packages/opencode-telegram-connect*`
|
|
87
|
+
3. Restart OpenCode.
|
|
41
88
|
|
|
42
|
-
|
|
89
|
+
Optionally also delete your credentials file (`~/.config/opencode/telegram.env`).
|
|
43
90
|
|
|
44
|
-
1.
|
|
45
|
-
2. Sende ihm `/newbot`.
|
|
46
|
-
3. Wähle einen Anzeigenamen und einen verfügbaren Benutzernamen für deinen Bot. Der Benutzername endet auf `bot`.
|
|
47
|
-
4. BotFather gibt dir einen API-Token. Bewahre ihn wie ein Passwort auf.
|
|
48
|
-
5. Öffne den Chat mit deinem neuen Bot und sende ihm eine normale Nachricht wie `Hallo`. Eine Antwort ist zu diesem Zeitpunkt noch nicht zu erwarten.
|
|
91
|
+
## 1. Get a bot and token
|
|
49
92
|
|
|
50
|
-
|
|
93
|
+
1. Open the official [@BotFather](https://t.me/BotFather) in Telegram.
|
|
94
|
+
2. Send it `/newbot`.
|
|
95
|
+
3. Choose a display name and an available username for your bot. The username must end in `bot`.
|
|
96
|
+
4. BotFather gives you an API token. Treat it like a password.
|
|
97
|
+
5. Open the chat with your new bot and send it a normal message such as `Hallo`. No answer is expected at this point.
|
|
51
98
|
|
|
52
|
-
|
|
99
|
+
The token belongs to the bot. Your personal user ID is determined separately in the next step. Telegram's own guide: [create a bot](https://core.telegram.org/bots/tutorial#obtain-your-bot-token).
|
|
53
100
|
|
|
54
|
-
|
|
101
|
+
## 2. Store token and user ID
|
|
55
102
|
|
|
56
|
-
|
|
57
|
-
- Linux/macOS: `~/.config/opencode/telegram.env`
|
|
103
|
+
Create this file:
|
|
58
104
|
|
|
59
|
-
|
|
105
|
+
- Windows: `C:\Users\<YOUR-NAME>\.config\opencode\telegram.env`
|
|
106
|
+
- Linux/macOS/WSL: `~/.config/opencode/telegram.env`
|
|
107
|
+
|
|
108
|
+
On Windows you can open it with:
|
|
60
109
|
|
|
61
110
|
```powershell
|
|
62
111
|
New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\opencode" | Out-Null
|
|
63
112
|
notepad "$env:USERPROFILE\.config\opencode\telegram.env"
|
|
64
113
|
```
|
|
65
114
|
|
|
66
|
-
|
|
115
|
+
Start with your real bot token:
|
|
67
116
|
|
|
68
117
|
```ini
|
|
69
118
|
TELEGRAM_TOKEN=DEIN_BOT_TOKEN
|
|
70
119
|
```
|
|
71
120
|
|
|
72
|
-
|
|
121
|
+
Save the file exactly as `telegram.env`, not `telegram.env.txt`.
|
|
73
122
|
|
|
74
|
-
###
|
|
123
|
+
### Find your user ID
|
|
75
124
|
|
|
76
|
-
|
|
125
|
+
Keep the Telegram connection off in OpenCode. After you have privately sent your bot `Hallo`, run:
|
|
77
126
|
|
|
78
127
|
```sh
|
|
79
|
-
npx --yes --package=opencode-telegram-connect@1.0.
|
|
128
|
+
npx --yes --package=opencode-telegram-connect@1.0.1 opencode-telegram-user-id
|
|
80
129
|
```
|
|
81
130
|
|
|
82
|
-
|
|
131
|
+
The helper reads the token from your file and prints the user IDs of pending messages, for example `DeinName: TELEGRAM_USER=123456789`. It sends no message and never prints the token. If several people are listed, take your own ID. If nothing is listed, send `Hallo` again and repeat. No other application may poll this bot while you do this.
|
|
83
132
|
|
|
84
|
-
|
|
133
|
+
Then complete the file:
|
|
85
134
|
|
|
86
135
|
```ini
|
|
87
136
|
TELEGRAM_TOKEN=DEIN_BOT_TOKEN
|
|
@@ -89,117 +138,146 @@ TELEGRAM_USER=123456789
|
|
|
89
138
|
TELEGRAM_PAIRING=false
|
|
90
139
|
```
|
|
91
140
|
|
|
92
|
-
|
|
141
|
+
The user ID is a number, not an `@username` and not the bot's ID. Multiple allowed users are separated by commas. With this configuration only the listed users can control the bot.
|
|
93
142
|
|
|
94
|
-
|
|
143
|
+
You need no npm token for installation or use. Your model API key belongs in the OpenCode model configuration, not in this file. Never copy the token into prompts, screenshots, or the repository.
|
|
95
144
|
|
|
96
|
-
##
|
|
145
|
+
## 3. Connect and first test
|
|
97
146
|
|
|
98
|
-
|
|
147
|
+
Start OpenCode in your project folder:
|
|
99
148
|
|
|
100
149
|
```sh
|
|
101
|
-
cd
|
|
150
|
+
cd path/to/your/project
|
|
102
151
|
opencode
|
|
103
152
|
```
|
|
104
153
|
|
|
105
|
-
|
|
154
|
+
Tell your OpenCode agent:
|
|
106
155
|
|
|
107
|
-
>
|
|
156
|
+
> Connect this session to Telegram. Use telegram_connect.
|
|
108
157
|
|
|
109
|
-
|
|
158
|
+
Only this tool call validates the token and starts Telegram polling. The bot then automatically sends you the usage guide. For that you must have written to it privately once and must not have blocked it. With static allowlist disabled, the guide appears only after successful pairing. Delivery errors are reported at connect time; the connection stays usable.
|
|
110
159
|
|
|
111
|
-
|
|
160
|
+
Then send your bot:
|
|
112
161
|
|
|
113
162
|
```text
|
|
114
163
|
/current
|
|
115
164
|
```
|
|
116
165
|
|
|
117
|
-
|
|
166
|
+
The output shows the selected session. Then send:
|
|
118
167
|
|
|
119
168
|
```text
|
|
120
|
-
|
|
169
|
+
Reply with HALLO only.
|
|
121
170
|
```
|
|
122
171
|
|
|
123
|
-
|
|
172
|
+
You first receive the session ID and then the model answer. The model works with the tools and permissions of your running OpenCode instance.
|
|
124
173
|
|
|
125
|
-
##
|
|
174
|
+
## 4. Using it in Telegram
|
|
126
175
|
|
|
127
|
-
|
|
|
176
|
+
| Message/Command | Function |
|
|
128
177
|
| --- | --- |
|
|
129
|
-
|
|
|
130
|
-
| `/start`
|
|
131
|
-
| `/current` |
|
|
132
|
-
| `/sessions` |
|
|
133
|
-
| `/session 2` |
|
|
134
|
-
| `/session <id>` |
|
|
135
|
-
| `/new
|
|
136
|
-
| `/rename
|
|
137
|
-
| `/models` |
|
|
138
|
-
| `/model 2` |
|
|
139
|
-
| `/model
|
|
140
|
-
| `/abort` |
|
|
141
|
-
| `/permissions` |
|
|
142
|
-
| `/approve <id>` |
|
|
143
|
-
| `/always <id>` |
|
|
144
|
-
| `/deny <id>` |
|
|
145
|
-
| `/questions` |
|
|
146
|
-
| `/answer <id>
|
|
147
|
-
| `/rejectquestion <id>` |
|
|
148
|
-
| `/disconnect` |
|
|
178
|
+
| Plain text | Send as a prompt to the selected session |
|
|
179
|
+
| `/start` or `/help` | Show the full usage guide |
|
|
180
|
+
| `/current` | Show current session and model |
|
|
181
|
+
| `/sessions` | List up to 20 sessions |
|
|
182
|
+
| `/session 2` | Select a session from the list |
|
|
183
|
+
| `/session <id>` | Select a session by its listed ID |
|
|
184
|
+
| `/new My test` | Create and select a new session |
|
|
185
|
+
| `/rename New title` | Rename the current session |
|
|
186
|
+
| `/models` | List available models |
|
|
187
|
+
| `/model 2` | Select a model from the list |
|
|
188
|
+
| `/model provider/model` | Select a model by its full name |
|
|
189
|
+
| `/abort` | Abort the running turn |
|
|
190
|
+
| `/permissions` | Show open permission requests |
|
|
191
|
+
| `/approve <id>` | Allow once |
|
|
192
|
+
| `/always <id>` | Permanently allow the matching permission |
|
|
193
|
+
| `/deny <id>` | Deny the permission |
|
|
194
|
+
| `/questions` | Show open questions |
|
|
195
|
+
| `/answer <id> answer` | Answer a question |
|
|
196
|
+
| `/rejectquestion <id>` | Reject a question |
|
|
197
|
+
| `/disconnect` | Remove this chat's binding; static user allowlists remain valid |
|
|
149
198
|
|
|
150
|
-
|
|
199
|
+
For multiple questions: `/answer <id> answer one || answer two`. For multi-select: `Option A; Option B`. For simple choice questions and permissions you can use the inline buttons sent along.
|
|
151
200
|
|
|
152
|
-
|
|
201
|
+
Other slash commands are forwarded to OpenCode as text; they do not automatically execute an OpenCode slash command. The removed start command is explicitly excluded from this.
|
|
153
202
|
|
|
154
|
-
### Telegram
|
|
203
|
+
### Turning Telegram off completely
|
|
155
204
|
|
|
156
|
-
|
|
205
|
+
Tell your OpenCode agent:
|
|
157
206
|
|
|
158
|
-
>
|
|
207
|
+
> Disconnect Telegram. Use telegram_disconnect.
|
|
159
208
|
|
|
160
|
-
|
|
209
|
+
This stops polling and releases the bot lock. `/disconnect` in Telegram only removes the chat binding. Abort a running job with `/abort` first; a full disconnect waits for in-flight message processing to finish.
|
|
161
210
|
|
|
162
|
-
|
|
211
|
+
After restarting OpenCode you must connect again. Only one OpenCode instance can be connected to the same bot at a time. Other instances do not take over the bot automatically. Disconnect the previous instance, then ask the desired agent to connect.
|
|
163
212
|
|
|
164
|
-
##
|
|
213
|
+
## Configuration
|
|
165
214
|
|
|
166
|
-
|
|
215
|
+
Existing environment variables take precedence. Accepted names:
|
|
167
216
|
|
|
168
|
-
| Variable |
|
|
217
|
+
| Variable | Meaning |
|
|
169
218
|
| --- | --- |
|
|
170
|
-
| `TELEGRAM_BOT_TOKEN` |
|
|
171
|
-
| `TELEGRAM_ALLOWED_USER_IDS` |
|
|
172
|
-
| `TELEGRAM_ALLOWED_CHAT_IDS` |
|
|
173
|
-
| `TELEGRAM_PAIRING` | `true`
|
|
174
|
-
| `TELEGRAM_ENV_FILE` |
|
|
219
|
+
| `TELEGRAM_BOT_TOKEN` | Environment variable for the bot token; files also accept `TELEGRAM_TOKEN` |
|
|
220
|
+
| `TELEGRAM_ALLOWED_USER_IDS` | Allowed users; files also accept `TELEGRAM_USER` |
|
|
221
|
+
| `TELEGRAM_ALLOWED_CHAT_IDS` | Allowed chats, comma-separated |
|
|
222
|
+
| `TELEGRAM_PAIRING` | `true` or `false` |
|
|
223
|
+
| `TELEGRAM_ENV_FILE` | Explicit path to a configuration file |
|
|
175
224
|
|
|
176
|
-
|
|
225
|
+
File lookup order: explicit path, global `telegram.env`, global `telegram.json`, then `.env.opencode-telegram` and `.env` in the project or parent directories. Prefer the global file. Restart OpenCode after changes so previously loaded values are replaced.
|
|
177
226
|
|
|
178
|
-
|
|
227
|
+
Alternative JSON format: `{"token":"DEIN_BOT_TOKEN","userId":"123456789"}`.
|
|
179
228
|
|
|
180
|
-
|
|
229
|
+
A chat allowlist lets every user in that chat control the session. User and chat allowlists are combined with OR. For private use, your user ID is enough.
|
|
181
230
|
|
|
182
|
-
|
|
231
|
+
Without a user/chat allowlist, one-time pairing is possible: `telegram_connect` returns a code you send to your bot as `/pair <code>`. The code expires after use or when the connection ends. With `TELEGRAM_PAIRING=false`, a static allowlist must be configured.
|
|
183
232
|
|
|
184
|
-
##
|
|
233
|
+
## Troubleshooting
|
|
185
234
|
|
|
186
|
-
- **Bot
|
|
187
|
-
- **Unauthorized:**
|
|
188
|
-
- **
|
|
189
|
-
- **
|
|
190
|
-
- **Webhook
|
|
191
|
-
- **
|
|
192
|
-
- **
|
|
235
|
+
- **Bot does not answer:** OpenCode must be running and `telegram_connect` must have succeeded. Check via the agent with `telegram_status`.
|
|
236
|
+
- **Unauthorized:** Check your numeric user ID and restart OpenCode after correcting it.
|
|
237
|
+
- **Token error:** Copy the token from BotFather into the file again. Check file name and path.
|
|
238
|
+
- **Another instance connected / Telegram Conflict:** Disconnect other OpenCode instances or programs polling the same bot.
|
|
239
|
+
- **Webhook conflict:** This plugin uses long polling. Use a dedicated bot without an existing webhook.
|
|
240
|
+
- **No model answer:** Test the same task directly in OpenCode first. Check model access, open permissions, and pending questions.
|
|
241
|
+
- **Tools missing:** Check the plugin entry, remove old local references, and restart OpenCode.
|
|
193
242
|
|
|
194
|
-
##
|
|
243
|
+
## Smoke test from OpenCode
|
|
195
244
|
|
|
196
|
-
|
|
245
|
+
After connecting, send your bot:
|
|
246
|
+
|
|
247
|
+
```text
|
|
248
|
+
/current
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
The reply shows the selected session. Then send a plain message such as `Reply with HALLO only.` and confirm you receive the session ID followed by the model answer.
|
|
252
|
+
|
|
253
|
+
## Build and verification from source
|
|
254
|
+
|
|
255
|
+
From the repository directory:
|
|
256
|
+
|
|
257
|
+
```text
|
|
197
258
|
npm ci
|
|
198
259
|
npm test
|
|
199
260
|
npm run check
|
|
200
|
-
npm
|
|
261
|
+
npm pack
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
`npm test` verifies authorization, pairing, session and model selection, permissions, questions, the real SDK request format with a simulated HTTP transport, and the connection lifecycle without network access.
|
|
265
|
+
|
|
266
|
+
## Publishing
|
|
267
|
+
|
|
268
|
+
The npm package name is `opencode-telegram-connect`.
|
|
269
|
+
|
|
270
|
+
```text
|
|
271
|
+
npm login
|
|
272
|
+
npm publish --access public
|
|
201
273
|
```
|
|
202
274
|
|
|
203
|
-
|
|
275
|
+
The package declares `win32`, `linux`, and `darwin` as installable npm platforms because the plugin is pure Node.js and runs on every platform OpenCode supports.
|
|
276
|
+
|
|
277
|
+
## Maintainer
|
|
278
|
+
|
|
279
|
+
Joel Buchholz
|
|
280
|
+
|
|
281
|
+
## License
|
|
204
282
|
|
|
205
|
-
|
|
283
|
+
MIT © 2026 Joel Buchholz
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "opencode-telegram-connect",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "Native OpenCode plugin to securely control sessions from Telegram.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./src/index.js",
|
|
@@ -24,9 +24,23 @@
|
|
|
24
24
|
"agent",
|
|
25
25
|
"remote-control"
|
|
26
26
|
],
|
|
27
|
+
"author": "Joel Buchholz",
|
|
27
28
|
"license": "MIT",
|
|
29
|
+
"repository": {
|
|
30
|
+
"type": "git",
|
|
31
|
+
"url": "git+https://github.com/joel-buchholz/opencode-telegram-control.git"
|
|
32
|
+
},
|
|
33
|
+
"os": [
|
|
34
|
+
"win32",
|
|
35
|
+
"linux",
|
|
36
|
+
"darwin"
|
|
37
|
+
],
|
|
28
38
|
"engines": {
|
|
29
|
-
"node": ">=20"
|
|
39
|
+
"node": ">=20",
|
|
40
|
+
"opencode": ">=1.18.0"
|
|
41
|
+
},
|
|
42
|
+
"publishConfig": {
|
|
43
|
+
"access": "public"
|
|
30
44
|
},
|
|
31
45
|
"peerDependencies": {
|
|
32
46
|
"@opencode-ai/plugin": ">=1.0.0"
|