opencode-telegram-notification

OpenCode plugin that sends Telegram notifications via LLM tool calls and critical event hooks, with bidirectional reply support.

Installation

bun add opencode-telegram-notification
# or
npm install opencode-telegram-notification

Then add the plugin to your opencode.json:

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

Setup

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts
3. Copy the bot token BotFather gives you

2. Set the Bot Token

export OPENCODE_NOTIFICATION_TELEGRAM_BOT_TOKEN="your-bot-token"

3. Send a Message to Your Bot

Open your bot in Telegram and send any message (e.g. "hello"). The plugin will automatically detect your chat_id on startup.

That's it! The plugin will start sending notifications and listening for your replies.

Environment Variables

| Variable | Required | Description | |---|---|---| | OPENCODE_NOTIFICATION_TELEGRAM_BOT_TOKEN | Yes | Bot token from BotFather | | OPENCODE_NOTIFICATION_TELEGRAM_CHAT_ID | No | Chat ID (auto-detected if not set) |

How It Works

Tool: send_notification

The plugin registers a send_notification tool that the LLM can call to send you a Telegram message. The LLM decides when to notify you — typically after completing a significant task or when it has important information you should see while away.

Urgency levels:

| Level | Behavior | |---|---| | low | Silent notification (no sound) | | normal | Default notification | | high | Ensures notification sound |

Event-Based Notifications

The plugin automatically sends notifications for critical events:

• permission.updated — LLM needs your permission to proceed
• question.asked — LLM asked a question that needs your answer
• session.error — Session encountered an error

Duplicate notifications for the same event within 10 seconds are suppressed. Notifications from child sessions (subagents) are filtered out.

Reply-to-Prompt

Reply to any bot notification in Telegram and your message will be injected as a prompt into the corresponding OpenCode session. The agent will process your request and send the result back via notification.

• Reply is confirmed with a 👍 reaction on your message
• If the reply fails, a 👎 reaction is shown instead
• The agent is instructed to notify you of the result since you're away from the terminal
• Messages sent directly in the terminal are not affected

This creates a bidirectional loop: notification → reply → agent processes → notification → reply...

Polling

The plugin uses Telegram long-polling (getUpdates with 30s timeout) to listen for replies. This runs in the background with minimal resource usage. Polling stops automatically after 3 consecutive failures.

License

MIT