opencode-telegram-bot-plugin

OpenCode plugin that sends smart Telegram notifications — only what matters, beautifully formatted.

Features

• 🔔 Permission request handling with inline buttons (Allow / Always / Reject)
• ✨ Smart idle notifications — shows whether the session completed or is waiting for your input
• 📊 Session summary with file change stats and expandable file list
• 📋 Todo completion summaries
• ❌ Error notifications — filtered to only show real errors (not aborts or subagent noise)
• 🤫 Subagent noise filtering — background/unnamed sessions are silently ignored
• 🌐 Multi-language support (Korean, English)
• 🔁 Duplicate notification prevention with configurable TTL
• ⚡ 409 Conflict safe — multiple OpenCode instances don't fight over polling

Installation

npm install -g opencode-telegram-bot-plugin

Update

npm update -g opencode-telegram-bot-plugin

After updating, restart OpenCode.

Setup

1. Create a Telegram Bot

1. Message @BotFather on Telegram
2. Send /newbot and follow the instructions
3. Copy the bot token

2. Get Your Chat ID

1. Send any message to your bot
2. Open: https://api.telegram.org/bot<TOKEN>/getUpdates
3. Find "chat":{"id":123456789} — that's your chat ID

3. Set Environment Variables

export OPENCODE_TELEGRAM_BOT_TOKEN="your-bot-token"
export OPENCODE_TELEGRAM_CHAT_ID="your-chat-id"

Note: This plugin uses the OPENCODE_TELEGRAM_ prefix to avoid conflicts with other Telegram plugins (e.g. Claude Code's TELEGRAM_BOT_TOKEN).

4. Add to OpenCode Global Config

Add to ~/.config/opencode/opencode.json:

{
  "plugin": [
    "opencode-telegram-bot-plugin"
  ]
}

5. Restart OpenCode

opencode

Configuration

| Variable | Description | Default | |----------|-------------|---------| | OPENCODE_TELEGRAM_BOT_TOKEN | Your Telegram bot token (required) | - | | OPENCODE_TELEGRAM_CHAT_ID | Your Telegram chat ID (required) | - | | OPENCODE_TELEGRAM_LANGUAGE | Language for notifications (ko or en) | ko | | OPENCODE_TELEGRAM_NOTIFY_SESSION | Session idle notifications | true | | OPENCODE_TELEGRAM_NOTIFY_PERMISSION | Permission request notifications | true | | OPENCODE_TELEGRAM_NOTIFY_TODO | Todo completion notifications | true | | OPENCODE_TELEGRAM_NOTIFY_SUBTASK | Subtask start notifications | true | | OPENCODE_TELEGRAM_NOTIFY_ERROR | Error notifications | true | | OPENCODE_TELEGRAM_NOTIFY_FILE_LIST | Expandable file list in session summary | true | | OPENCODE_TELEGRAM_DEDUP_ENABLED | Enable duplicate notification filtering | true | | OPENCODE_TELEGRAM_DEDUP_TTL_MS | Deduplication TTL in milliseconds | 300000 (5 min) |

Noise Filtering

The plugin automatically suppresses notifications from:

• Subagents — sessions with titles like (@explore subagent), (@oracle subagent) etc.
• Unnamed background sessions — sessions where the title is just a raw session ID (ses_xxxx)
• Generic errors — The operation was aborted. and Model not found: errors are silently dropped
• Todo completions from subagent/background sessions are also suppressed
• Subtask notifications from subagent sessions or with subagent-style agent names are also suppressed

This keeps your Telegram clean when using multi-agent workflows like Oh My OpenCode.

Idle Notification Debounce

Idle notifications are delayed 15 seconds before being sent. If the session goes busy again within that window (e.g. due to system-reminder injections), the notification is cancelled.

This prevents rapid idle→busy→idle cycles from spamming your Telegram.

Smart Wait Detection

When a session goes idle, the plugin checks if there are unfinished todos:

• Unfinished todos remaining → ⏳ 사용자 입력을 기다리고 있습니다 — you need to act
• All todos done → ✨ 작업 완료 및 사용자 대기 — clean completion

No extra LLM calls or API requests — uses already-received todo event data.

Notification Filtering

Control which notifications you receive:

export OPENCODE_TELEGRAM_NOTIFY_SESSION="false"     # Disable session idle
export OPENCODE_TELEGRAM_NOTIFY_FILE_LIST="false"   # Disable file list
export OPENCODE_TELEGRAM_NOTIFY_TODO="false"        # Disable todo summaries
export OPENCODE_TELEGRAM_NOTIFY_SUBTASK="false"     # Disable subtask notifications
export OPENCODE_TELEGRAM_NOTIFY_ERROR="false"       # Disable errors (not recommended)

Permission notifications cannot be disabled as they require your response.

Deduplication

Prevents duplicate notifications within a time window:

export OPENCODE_TELEGRAM_DEDUP_ENABLED="true"
export OPENCODE_TELEGRAM_DEDUP_TTL_MS="600000"   # 10 minutes

Notification Reference

| Event | Notification | |-------|-------------| | Task completes (waiting for input) | ⏳ Waiting for user input | | Task completes (all done) | ✨ Task completed | | Permission needed | 🔔 Permission Request (with buttons) | | All todos done | 📋 All Tasks Complete | | Error occurred | ❌ Error (real errors only) |

License

MIT