claude-notify-telegram

Get Telegram notifications when Claude Code finishes a task or needs attention. Know when to come back and assign new work.

What you get

When Claude finishes a task (Stop event):

✅ my-project — task finished

┌─────────────────────────────────────────────────┐
│ I've implemented the authentication module and  │
│ added tests. All 12 tests pass.                 │
└─────────────────────────────────────────────────┘

When Claude needs attention (Notification event):

🔔 my-project — notification

Claude is waiting for permission to run: npm test

Setup

1. Create a Telegram Bot

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts
3. Copy the bot token (looks like 123456:ABC-DEF1234...)

2. Get your Chat ID

1. Message your new bot (send anything)
2. Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
3. Find "chat":{"id": in the response — that number is your chat ID

3. Configure credentials

Option A: Config file (recommended)

mkdir -p ~/.config/claude-notify-telegram
cat > ~/.config/claude-notify-telegram/config << 'EOF'
TELEGRAM_BOT_TOKEN="your-bot-token"
TELEGRAM_CHAT_ID="your-chat-id"
EOF
chmod 600 ~/.config/claude-notify-telegram/config

Option B: Environment variables

Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export CLAUDE_NOTIFY_TG_TOKEN="your-bot-token"
export CLAUDE_NOTIFY_TG_CHAT_ID="your-chat-id"

The plugin-specific CLAUDE_NOTIFY_TG_* names avoid conflicts if you already use TELEGRAM_BOT_TOKEN for something else. The generic names (TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID) also work as a fallback.

4. Install the plugin

From a local path:

claude plugin marketplace add /path/to/claude-notify-telegram
claude plugin install claude-notify-telegram

Or from a git URL:

claude plugin marketplace add https://github.com/user/claude-notify-telegram
claude plugin install claude-notify-telegram

Requirements

• jq — install with apt install jq / brew install jq
• curl — pre-installed on most systems

How it works

The plugin registers hooks for Claude Code's Stop and Notification events. When triggered, it extracts the relevant message and project name, then sends a formatted message to your Telegram bot.

If no credentials are configured, the plugin silently does nothing. Notification failures never block Claude.