@jshsakura/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 @jshsakura/opencode-telegram-bot-plugin

Update

npm update -g @jshsakura/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": [
    "@jshsakura/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 (v1.1.0+)

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 (v1.1.4+)
• Subtask notifications from subagent sessions or with subagent-style agent names are also suppressed (v1.1.4+)

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

Idle Notification Debounce (v1.1.2+)

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 (v1.1.0+)

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