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

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

2. Get Your Chat ID

1. Send any message to your new bot (e.g. /start)
2. Open this URL in your browser (replace <TOKEN> with your bot token):

   https://api.telegram.org/bot<TOKEN>/getUpdates

3. 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

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

License

MIT