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