copilot-telegram-notify

copilot-telegram-notify is a GitHub Copilot CLI plugin that sends Telegram notifications when a task finishes and when a session ends.

It is useful when you run Copilot in the terminal and want a private Telegram message with the result instead of constantly checking the terminal window.

Features

• Sends a Telegram summary when a Copilot session ends.
• Sends per-task notifications by default when a task finishes.
• Tracks prompts and tool usage during the session to build useful summaries.
• Loads configuration from .env files or existing environment variables.
• Works when installed as a Copilot CLI plugin instead of only from the repo folder.

Requirements

• GitHub Copilot CLI with plugin support
• Node.js
• A Telegram bot token
• A Telegram chat ID

Installation

Install from source

git clone <your-repo-url>
cd copilot-telegram-notify
npm install
cp .env.example .env
copilot plugin install ./

If you change the plugin locally after installing it from a path, reinstall it so Copilot refreshes the installed plugin files:

copilot plugin uninstall copilot-telegram-notify
copilot plugin install ./

Configuration

Create a .env file based on .env.example:

cp .env.example .env

Required variables

TELEGRAM_BOT_TOKEN=123456789:AA_your_botfather_token_here
TELEGRAM_CHAT_ID=123456789

Optional variables

# Send a Telegram message after each finished task. Set to 0 to only notify at session end.
COPILOT_TELEGRAM_NOTIFY_EACH_TASK=1

# Custom state directory. Defaults to ~/.copilot-telegram
# COPILOT_TELEGRAM_STATE_DIR=/absolute/path/to/state

Environment loading order

The plugin loads configuration from these locations, in order:

1. The plugin folder .env
2. The current working directory .env
3. ~/.copilot-telegram/.env
4. ~/.config/copilot-telegram-notify/.env
5. Existing shell environment variables

For a global install, a practical shared location is:

mkdir -p ~/.copilot-telegram
cp .env.example ~/.copilot-telegram/.env

Get your Telegram chat ID

1. Create your bot with BotFather if you have not already.
2. Send your bot a message in Telegram.
3. Run:

node scripts/get-chat-id.mjs

Or query the Bot API directly:

curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates"

Then look for message.chat.id in the response.

How it works

The plugin registers Copilot CLI hooks and keeps lightweight session state so it can summarize what happened during the run.

• agentStop sends per-task notifications by default
• sessionEnd sends the full session summary
• prompts and tool activity are tracked throughout the session

If Telegram is not configured, the hook writes a clear error to stderr instead of pretending the notification was sent.

Development

Validate the hook scripts:

npm run check

License

MIT