OpenCode Telegram Notification

Lightweight Telegram-only notification plugin for OpenCode. Fork of @goodnesshq/opencode-notification with inline/oneliner setup support.

Run setup once from any directory, and notifications apply to every OpenCode session, including sessions started outside Git repos.

Blank titles resolve to the basename of the emitting session directory. For example, a session started from /Users/matt/Developer/my-project notifies as my-project.

Quick Start

Interactive setup

npx @israel_eb/opencode-telegram-notification setup

This will:

• Copy the plugin to ~/.config/opencode/plugins/opencode-notifications.mjs
• Update ~/.config/opencode/opencode.json
• Launch the interactive installer and write ~/.config/opencode/oc-notify.json

Inline / one-liner setup (non-interactive)

Pass everything as CLI arguments — no prompts:

npx @israel_eb/opencode-telegram-notification setup \
  --token 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 \
  --chat-id 987654321

All options

npx @israel_eb/opencode-telegram-notification setup \
  --token <bot-token>           # Telegram bot token (required for non-interactive)
  --chat-id <peer-id>           # Telegram chat/group Peer ID (required for non-interactive)
  --title "My Custom Title"     # Optional: override notification title
  --enabled                     # Enable notifications (default)
  --no-enabled                  # Disable notifications
  --ignore-subagents            # Suppress subagent notifications (default)
  --no-ignore-subagents         # Show subagent notifications too
  --test                        # Send test notification (default)
  --no-test                     # Skip test notification
  --yes                         # Non-interactive mode, use all provided values

Examples:

# Minimal — just token and chat ID, everything else uses defaults
npx @israel_eb/opencode-telegram-notification setup --token 123:ABC --chat-id 456

# Full control
npx @israel_eb/opencode-telegram-notification setup \
  --token 123:ABC \
  --chat-id -987654321 \
  --title "OpenCode Alerts" \
  --no-ignore-subagents \
  --no-test

If you use a long-running OpenCode process such as opencode serve, opencode web, or an attached client session, restart that process after setup or plugin updates so OpenCode reloads the global plugin.

Prerequisites

Before running setup, find your Telegram bot token and chat ID. See docs/telegram-chat-id.md.

To suppress npm update notices during npx runs:

npm config set update-notifier false
# Or for a single run:
npm_config_update_notifier=false npx @israel_eb/opencode-telegram-notification@latest setup --token ... --chat-id ...

What Triggers Notifications

The plugin only sends Telegram messages for:

• permission.asked
• question.asked
• session.idle

By default, subagent notifications are ignored so session.idle does not spam you for subagent runs.

Permission notifications are delayed briefly. If OpenCode auto-accepts the permission immediately, the notification is suppressed and nothing is sent.

Config

The global config lives at ~/.config/opencode/oc-notify.json and uses this minimal shape:

{
  "enabled": true,
  "title": "",
  "ignoreSubagents": true,
  "telegram": {
    "token": "<bot-token>",
    "chatId": "<peer-id>"
  }
}

• enabled: master switch for all notifications
• title: optional fixed title; leave blank to use the session directory basename
• ignoreSubagents: suppress notifications whose subtitle or body contains an OpenCode subagent marker
• telegram.token: Telegram bot token
• telegram.chatId: Telegram chat or group peer ID