Claude Code Telegram notification hook — fires on plan-scale executions only

telegram-notify.sh

#!/usr/bin/env bash
# Claude Code notification via Telegram
# Stop/StopFailure: only fires after substantial multi-tool executions.
# Notification: fires when the agent needs your attention mid-execution.

TELEGRAM_BOT_TOKEN="8061451293:AAFMzFLgPPOsZNNgbj6PmvlSyEKs2z_O0Is"
TELEGRAM_CHAT_ID="1953804652"

# Minimum tool calls before a Stop event triggers a notification.
# Single-turn responses won't notify; only plan-scale executions will.
TOOL_THRESHOLD=5

# Read JSON from stdin
INPUT=$(cat)

SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "unknown"')
CWD=$(echo "$INPUT" | jq -r '.cwd // "unknown"')

PROJECT=$(basename "$CWD")
HOSTNAME=$(hostname)

COUNTER_FILE="/tmp/cc-tools-${SESSION_ID}"

case "$HOOK_EVENT" in
  PostToolUse)
    # Increment per-session tool counter
    echo "1" >> "$COUNTER_FILE"
    exit 0
    ;;

  Stop)
    # Count tools used this session, then clear
    if [[ -f "$COUNTER_FILE" ]]; then
      TOOL_COUNT=$(wc -l < "$COUNTER_FILE" | tr -d ' ')
      rm -f "$COUNTER_FILE"
    else
      TOOL_COUNT=0
    fi
    # Skip notification for lightweight single-turn responses
    if [[ "$TOOL_COUNT" -lt "$TOOL_THRESHOLD" ]]; then
      exit 0
    fi
    EMOJI="✅"
    DESCRIPTION="Plan execution complete (${TOOL_COUNT} tools used)."
    ;;

  StopFailure)
    # Always notify on errors; clean up counter if present
    rm -f "$COUNTER_FILE"
    TOOL_COUNT=""
    EMOJI="❌"
    DESCRIPTION="Agent stopped due to an API error."
    ;;

  Notification)
    TOOL_COUNT=""
    EMOJI="🔔"
    DESCRIPTION=$(echo "$INPUT" | jq -r '.message // "Agent needs your attention."')
    ;;

  *)
    TOOL_COUNT=""
    EMOJI="⏸️"
    DESCRIPTION="Agent halted (event: $HOOK_EVENT)."
    ;;
esac

TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S %Z')

MESSAGE="${EMOJI} *${HOSTNAME} / ${PROJECT} — ${HOOK_EVENT}*

${DESCRIPTION}

📂 \`${CWD}\`
🕐 ${TIMESTAMP}
🔑 Session: \`${SESSION_ID:0:12}…\`"

# Fire and forget — don't block Claude
curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -d chat_id="$TELEGRAM_CHAT_ID" \
  -d text="$MESSAGE" \
  -d parse_mode="Markdown" \
  > /dev/null 2>&1 &

exit 0

telegram-notify_setup.md

telegram-notify.sh — Claude Code Telegram Hook

Sends a Telegram notification when Claude Code finishes a substantial multi-tool execution. Single-turn responses are silently skipped (configurable threshold).

What it notifies

Event	When
✅ Stop	After ≥5 tool uses in a session (plan-scale work only)
❌ StopFailure	Always — API errors are always surfaced
🔔 Notification	When the agent needs mid-execution attention

The message header includes hostname / project-folder so you always know which machine and project fired it.

Prerequisites

• jq — JSON parsing (apt install jq / brew install jq)
• curl — HTTP requests (usually pre-installed)
• A Telegram bot token and your chat ID

Install

mkdir -p ~/.claude/hooks
curl -o ~/.claude/hooks/telegram-notify.sh \
  https://gist.githubusercontent.com/zudsniper/RAW_URL/telegram-notify.sh
chmod +x ~/.claude/hooks/telegram-notify.sh

Edit the script and set your credentials:

TELEGRAM_BOT_TOKEN="your-bot-token-here"
TELEGRAM_CHAT_ID="your-chat-id-here"

To find your chat ID: message your bot, then visit: https://api.telegram.org/bot<TOKEN>/getUpdates

Settings

Add to ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/telegram-notify.sh", "timeout": 5, "async": true }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/telegram-notify.sh", "timeout": 10 }]
      }
    ],
    "StopFailure": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/telegram-notify.sh", "timeout": 10 }]
      }
    ]
  }
}

Tuning the threshold

The TOOL_THRESHOLD variable (default: 5) controls how many tool uses must occur before a Stop notification fires. Raise it for noisier workloads, lower it if you want notifications sooner.

TOOL_THRESHOLD=5