opencode-telegram

OpenCode plugin that sends Telegram notifications when tasks complete, and lets you respond to permission requests directly from your phone.

Zero external dependencies — uses Node.js https module directly.

Quick Start

1. Create a Telegram Bot

Open Telegram and message @BotFather
Send /newbot, pick a name and username
Copy the bot token (e.g. 123456:ABC-DEF...)

2. Get Your Chat ID

Send any message to your new bot (e.g. /start)
Open this URL in your browser (replace <TOKEN> with your bot token):
```
https://api.telegram.org/bot<TOKEN>/getUpdates
```
Find "chat":{"id":123456789} in the response — that number is your chat ID

3. Set Environment Variables

Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export TELEGRAM_BOT_TOKEN="your-bot-token"
export TELEGRAM_CHAT_ID="your-chat-id"

Then reload: source ~/.bashrc

4. Add Plugin to OpenCode

Add "opencode-telegram" to the plugin array in ~/.config/opencode/opencode.json:

{
  "plugin": [
    "opencode-telegram"
    // ...your other plugins
  ]
}

5. Restart OpenCode

opencode

You should see [opencode-telegram] Bot polling started in the logs. That's it — you'll now receive Telegram notifications.

What You Get

Event	Notification	Interactive?
Task completes	✅ Task Complete — session title	No
Permission needed	🔔 Permission Request — action details	Yes — tap Allow / Always / Reject
All todos done	📋 All Tasks Complete — todo list summary	No
Subtask spawned	🔀 Subtask Started — agent name + description	No
Session error	❌ Error — error message	No

Permission Responses

When OpenCode needs permission (file edits, bash commands, etc.), you get a message with three buttons:

✅ Allow — allow this one time
✅ Always — always allow this pattern going forward
❌ Reject — deny the request

Your response is sent back to OpenCode immediately — no need to be at your terminal.

Environment Variables

Variable	Required	Description
`TELEGRAM_BOT_TOKEN`	Yes	Bot token from @BotFather
`TELEGRAM_CHAT_ID`	Yes	Your Telegram chat ID (numeric)

If either variable is missing, the plugin silently disables itself and OpenCode runs normally.

How It Works

OpenCode Events ──→ Plugin (event hook) ──→ Telegram Bot API
                                                  │
Telegram Button Press ←── Long Polling ←──────────┘
         │
         └──→ Plugin ──→ OpenCode SDK (permission reply)

Listens to OpenCode events via the official @opencode-ai/plugin hook system
Sends notifications using Telegram Bot API over HTTPS (IPv4, no external dependencies)
Receives button presses via long polling (no webhook server needed)
Replies to permission requests via the OpenCode SDK client

Troubleshooting

No notifications?

Check that both env vars are set: echo $TELEGRAM_BOT_TOKEN $TELEGRAM_CHAT_ID
Look for [opencode-telegram] in OpenCode logs
Make sure you sent at least one message to the bot first

Connection timeout?

The plugin forces IPv4 connections. If your server blocks outbound HTTPS to api.telegram.org, the plugin will log errors but won't crash OpenCode.

Buttons not responding?

Long polling only runs while OpenCode is active
If you pressed a button after closing OpenCode, restart it — the response will be processed on next poll

Uninstall

Remove "opencode-telegram" from opencode.json's plugin array
Remove the env vars from your shell profile
Restart OpenCode

License

MIT