Skip to content

Commit cac51c6

Browse files
jon23djon23d
authored
Merge pull request #3 from jon23d/feature/add-twilio-integration
add telegram integration
2 parents ae8f7c2 + 0c4a362 commit cac51c6

10 files changed

Lines changed: 478 additions & 39 deletions

File tree

‎.env.example‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Telegram Notifications Configuration
2+
# Copy this file to .env and fill in your Telegram credentials
3+
4+
# Enable/disable Telegram notifications
5+
TELEGRAM_ENABLED=true
6+
7+
# Your Telegram Bot Token (from @BotFather)
8+
TELEGRAM_BOT_TOKEN=your_bot_token_here
9+
10+
# Your Telegram Chat ID (see TELEGRAM_SETUP.md for how to obtain this)
11+
TELEGRAM_CHAT_ID=your_chat_id_here
12+
13+
# Optional: Container-specific environment variables
14+
# PORT=8080
15+
# HOSTNAME=opencode-container

‎AGENTS.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,17 @@ This file provides guidance for agentic coding agents operating in this reposito
88

99
```bash
1010
# Build main image
11-
docker build -t jdcode-dev .
11+
docker build -t jdcode-python .
1212

1313
# Build specific variant
1414
./build.sh python # Python development variant
1515
./build.sh ts # TypeScript development variant
1616

17-
# Run container
18-
docker run -it --rm -v "$PWD":/code -p 8080:8080 jdcode-dev
17+
# Run container (Python variant)
18+
docker run -it --rm -v "$PWD":/code -p 8080:8080 jdcode-python
1919

2020
# With password authentication
21-
docker run -it --rm -v "$PWD":/code -p 8080:8080 -e PASSWORD=secret jdcode-dev
21+
docker run -it --rm -v "$PWD":/code -p 8080:8080 -e PASSWORD=secret jdcode-python
2222

2323
# View logs
2424
docker logs <container-id>

‎README.md‎

Lines changed: 74 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -47,23 +47,81 @@ This will create Docker images tagged as `jdcode-python` and `jdcode-ts`.
4747

4848
> Note: Binding ports in docker uses the -p flag in the form HOST_PORT:CONTAINER_PORT
4949
50+
### Basic Usage
51+
5052
1. **Run the containers**:
5153
Start each environment by binding the appropriate port:
5254
- For Python:
5355
```bash
54-
docker run -it -v "$PWD":/code -p 8080:8080 jdcode-python
56+
docker run -it --rm -v "$PWD":/code -v /etc/localtime:/etc/localtime:ro -p 8080:8080 jdcode-python
5557
```
5658
- For TypeScript:
5759
```bash
58-
docker run -it -v "$PWD":/code -p 8080:8080 jdcode-ts
60+
docker run -it --rm -v "$PWD":/code -v /etc/localtime:/etc/localtime:ro -p 8080:8080 jdcode-ts
5961
```
6062

61-
3. **Access the VSCode instance**:
63+
> The `-v /etc/localtime:/etc/localtime:ro` mount syncs the container clock with your host timezone. Without it, the container defaults to UTC.
64+
65+
2. **Access the VSCode instance**:
6266
- Open your browser to `http://localhost:8080`
6367

64-
4. **Access Opencode**
68+
3. **Access OpenCode**
6569
- In your container, execute `opencode`
6670

71+
### With Telegram Notifications
72+
73+
Both variants include a Telegram notification plugin that sends messages via a Telegram bot when OpenCode session events occur (idle, errors, completion).
74+
75+
**Prerequisites:**
76+
- A Telegram bot created via [@BotFather](https://t.me/BotFather)
77+
- Your bot token and chat ID (see `TELEGRAM_SETUP.md` for details)
78+
79+
**Run with Telegram notifications enabled:**
80+
81+
- For Python:
82+
```bash
83+
docker run -it --rm \
84+
-v "$PWD":/code \
85+
-v /etc/localtime:/etc/localtime:ro \
86+
-p 8080:8080 \
87+
-e TELEGRAM_ENABLED=true \
88+
-e TELEGRAM_BOT_TOKEN=your_bot_token \
89+
-e TELEGRAM_CHAT_ID=your_chat_id \
90+
jdcode-python
91+
```
92+
93+
- For TypeScript:
94+
```bash
95+
docker run -it --rm \
96+
-v "$PWD":/code \
97+
-v /etc/localtime:/etc/localtime:ro \
98+
-p 8080:8080 \
99+
-e TELEGRAM_ENABLED=true \
100+
-e TELEGRAM_BOT_TOKEN=your_bot_token \
101+
-e TELEGRAM_CHAT_ID=your_chat_id \
102+
jdcode-ts
103+
```
104+
105+
**Using environment file:**
106+
Create a `.env` file with your credentials:
107+
```bash
108+
TELEGRAM_ENABLED=true
109+
TELEGRAM_BOT_TOKEN=your_bot_token_here
110+
TELEGRAM_CHAT_ID=your_chat_id_here
111+
```
112+
113+
Then run with:
114+
```bash
115+
docker run -it --rm -v "$PWD":/code -v /etc/localtime:/etc/localtime:ro -p 8080:8080 --env-file .env jdcode-ts
116+
```
117+
118+
**Notification Events:**
119+
- 🤖 Session idle notifications
120+
- ❌ Session error alerts
121+
- 🗑️ Session completion messages
122+
123+
See `.env.example` for a template configuration file.
124+
67125
---
68126

69127
## 🔗 Creating Aliases for Convenience
@@ -75,8 +133,13 @@ To avoid typing long docker commands, you can create shell aliases:
75133
Add these lines to your `~/.bashrc` or `~/.zshrc`:
76134

77135
```bash
78-
alias jdcode-python='docker run -it --rm -v "$PWD":/code -p 8080:8080 jdcode-python'
79-
alias jdcode-ts='docker run -it --rm -v "$PWD":/code -p 8080:8080 jdcode-ts'
136+
# Basic aliases
137+
alias jdcode-python='docker run -it --rm -v "$PWD":/code -v /etc/localtime:/etc/localtime:ro -p 8080:8080 jdcode-python'
138+
alias jdcode-ts='docker run -it --rm -v "$PWD":/code -v /etc/localtime:/etc/localtime:ro -p 8080:8080 jdcode-ts'
139+
140+
# With Telegram notifications (requires environment variables to be set)
141+
alias jdcode-python-notify='docker run -it --rm -v "$PWD":/code -v /etc/localtime:/etc/localtime:ro -p 8080:8080 -e TELEGRAM_ENABLED=true -e TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" -e TELEGRAM_CHAT_ID="$TELEGRAM_CHAT_ID" jdcode-python'
142+
alias jdcode-ts-notify='docker run -it --rm -v "$PWD":/code -v /etc/localtime:/etc/localtime:ro -p 8080:8080 -e TELEGRAM_ENABLED=true -e TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" -e TELEGRAM_CHAT_ID="$TELEGRAM_CHAT_ID" jdcode-ts'
80143
```
81144

82145
Then reload your shell configuration:
@@ -88,8 +151,13 @@ source ~/.bashrc # or source ~/.zshrc
88151

89152
After setting up the aliases, you can simply run:
90153
```bash
154+
# Basic usage
91155
jdcode-python # Start Python development environment
92156
jdcode-ts # Start TypeScript development environment
157+
158+
# With Telegram notifications (requires Telegram env vars)
159+
jdcode-python-notify # Python with Telegram notifications
160+
jdcode-ts-notify # TypeScript with Telegram notifications
93161
```
94162

95163
---

‎TELEGRAM_SETUP.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Telegram Notifications for OpenCode
2+
3+
This feature sends Telegram messages via the Bot API when OpenCode session events occur, such as when a session becomes idle or encounters an error.
4+
5+
## Setup
6+
7+
### 1. Create a Telegram Bot
8+
9+
1. Open Telegram and search for [@BotFather](https://t.me/BotFather)
10+
2. Send `/newbot` and follow the prompts to create a bot
11+
3. BotFather will give you a **Bot Token** (e.g., `123456789:ABCdefGhIjKlMnOpQrStUvWxYz`)
12+
13+
### 2. Get Your Chat ID
14+
15+
1. Start a conversation with your new bot (search for it by username and press **Start**)
16+
2. Send any message to the bot
17+
3. Open this URL in your browser (replace `YOUR_BOT_TOKEN`):
18+
```
19+
https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
20+
```
21+
4. Look for `"chat":{"id":123456789}` in the response — that number is your **Chat ID**
22+
23+
24+
> **Tip:** For group chats, add the bot to the group, send a message, and check `getUpdates`. Group chat IDs are typically negative numbers.
25+
26+
### 3. Configure Environment Variables
27+
28+
Set the following environment variables:
29+
30+
```bash
31+
# Required - Enable the feature
32+
export TELEGRAM_ENABLED=true
33+
34+
# Required - Your bot token from @BotFather
35+
export TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIjKlMnOpQrStUvWxYz
36+
37+
# Required - The chat ID to send messages to
38+
export TELEGRAM_CHAT_ID=987654321
39+
```
40+
41+
### 4. Run OpenCode Container
42+
43+
#### Basic Usage
44+
```bash
45+
docker run -it --rm \
46+
-v "$PWD":/code \
47+
-v /etc/localtime:/etc/localtime:ro \
48+
-p 8080:8080 \
49+
-e TELEGRAM_ENABLED=true \
50+
-e TELEGRAM_BOT_TOKEN=your_bot_token \
51+
-e TELEGRAM_CHAT_ID=your_chat_id \
52+
jdcode-python
53+
```
54+
55+
#### Using Environment File
56+
Create a `.env` file with your Telegram credentials:
57+
58+
```bash
59+
# .env
60+
TELEGRAM_ENABLED=true
61+
TELEGRAM_BOT_TOKEN=your_bot_token_here
62+
TELEGRAM_CHAT_ID=your_chat_id_here
63+
```
64+
65+
Then run with:
66+
```bash
67+
docker run -it --rm \
68+
-v "$PWD":/code \
69+
-v /etc/localtime:/etc/localtime:ro \
70+
-p 8080:8080 \
71+
--env-file .env \
72+
jdcode-python
73+
```
74+
75+
## Events That Trigger Notifications
76+
77+
The plugin sends Telegram messages for these OpenCode session events:
78+
79+
| Event | Message | When It Occurs |
80+
|-------|---------|---------------|
81+
| `session.created` | 🚀 ProjectName session started at [time] | When a new session is created |
82+
| `session.idle` | 🤖 ProjectName session has been idle since [time] | When OpenCode session becomes inactive |
83+
| `session.error` | ❌ ProjectName session encountered an error at [time] | When an error occurs in the session |
84+
| `session.deleted` | 🗑️ ProjectName session ended at [time] | When the session is terminated |
85+
86+
## Validation and Feedback
87+
88+
When the container starts, you'll see status messages:
89+
90+
### Properly Configured
91+
```
92+
🔔 Telegram notifications: ENABLED
93+
🤖 Bot token: 123456***xYz
94+
💬 Chat ID: 987654321
95+
✓ All required variables configured
96+
```
97+
98+
### Missing Variables
99+
```
100+
🔔 Telegram notifications: ENABLED
101+
⚠️ WARNING: Telegram enabled but missing required environment variables:
102+
- TELEGRAM_BOT_TOKEN
103+
Telegram notifications will not work until all variables are set.
104+
```
105+
106+
### Disabled
107+
```
108+
📵 Telegram notifications: DISABLED (set TELEGRAM_ENABLED=true to enable)
109+
```
110+
111+
## Security Notes
112+
113+
- **Bot tokens are masked** in logs and startup messages
114+
- **Credentials are only loaded from environment variables** (not stored in files)
115+
- The plugin only activates when `TELEGRAM_ENABLED=true` is explicitly set
116+
117+
## Troubleshooting
118+
119+
### No Messages Received
120+
1. Check that all environment variables are set correctly
121+
2. Verify you started a conversation with the bot (press Start in Telegram)
122+
3. Verify your chat ID is correct by checking `getUpdates`
123+
4. Check OpenCode logs for error messages:
124+
```bash
125+
docker logs <container-id>
126+
```
127+
128+
### Plugin Not Loading
129+
- The plugin is automatically loaded from `docker/base/.opencode/plugins/`
130+
- No npm dependencies are required (uses built-in `fetch()`)
131+
- Check OpenCode startup logs for plugin initialization messages
132+
133+
### Testing
134+
To test the notification functionality, you can trigger a session idle event by leaving OpenCode inactive for a period of time.
135+
136+
## Example Build and Run Script
137+
138+
Create a `run-with-telegram.sh` script:
139+
140+
```bash
141+
#!/bin/bash
142+
set -e
143+
144+
# Build the OpenCode image
145+
./build.sh
146+
147+
# Run with Telegram notifications
148+
docker run -it --rm \
149+
-v "$PWD":/code \
150+
-v /etc/localtime:/etc/localtime:ro \
151+
-p 8080:8080 \
152+
-e TELEGRAM_ENABLED=true \
153+
-e TELEGRAM_BOT_TOKEN="${TELEGRAM_BOT_TOKEN}" \
154+
-e TELEGRAM_CHAT_ID="${TELEGRAM_CHAT_ID}" \
155+
jdcode-python
156+
```
157+
158+
Make it executable and run:
159+
```bash
160+
chmod +x run-with-telegram.sh
161+
./run-with-telegram.sh
162+
```

‎docker/base/.opencode/package.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"name": "@opencode/docker-base-plugins",
3+
"version": "1.0.0",
4+
"description": "Plugin dependencies for OpenCode Docker base image",
5+
"dependencies": {},
6+
"engines": {
7+
"node": ">=18.0.0"
8+
}
9+
}

0 commit comments

Comments
 (0)