Brancher Claude Code à Telegram : un hook, pas un canal magique

Recevoir une notification Telegram quand Claude Code termine une tâche est une bonne idée, surtout pour les sessions longues en mode -p où l’on s’éloigne du terminal. Le piège, c’est qu’il n’existe ni drapeau --channel telegram, ni section taskComplete magique dans settings.json. Le bon mécanisme s’appelle un hook : un événement officiel de Claude Code qui exécute un script de votre choix, et c’est ce script qui appelle l’API Telegram.

Vendredi midi, j’ai lancé un claude -p chargé de migrer une centaine de fichiers dans un repo. J’avais quarante minutes avant un déjeuner. À mon retour, Claude avait terminé depuis vingt minutes, et je l’ai découvert en me rasseyant. C’est exactement le genre de signal qui devrait arriver sur le téléphone : j’ai fini, viens regarder.

Un hook officiel, un script de cinq lignes

La documentation des hooks liste une trentaine d’événements. Pour la notification de fin de tâche, celui qui compte est Stop, il se déclenche quand Claude finit de répondre. Dans ~/.claude/settings.json :

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "~/.claude/bin/telegram-notify.sh" }
        ]
      }
    ]
  }
}

Et le script ~/.claude/bin/telegram-notify.sh :

#!/usr/bin/env bash
set -euo pipefail
TOKEN="${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN manquant}"
CHAT_ID="${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID manquant}"
curl -sS "https://api.telegram.org/bot${TOKEN}/sendMessage" \
  -d chat_id="${CHAT_ID}" \
  -d text="Claude a terminé — $(pwd)" > /dev/null

C’est tout. Le bot se crée auprès de @BotFather (commande /newbot, deux questions, un token revient). Le chat_id se récupère en envoyant un message au bot puis en lisant https://api.telegram.org/bot<TOKEN>/getUpdates. Token et ID vivent dans ~/.zshenv ou un équivalent, jamais dans settings.json.

Trois événements qui couvrent 95 % des cas

Stop se déclenche quand Claude termine sa réponse. Pour les claude -p lancés en arrière-plan, c’est le seul qui compte, il dit “viens voir le diff”.

Notification se déclenche quand Claude Code veut vous parler en cours de session : besoin d’une permission, attente d’entrée, idle prolongé. Sur le téléphone, c’est ce qui remplace l’icône qui clignote dans la barre des tâches du mac.

SessionEnd ferme la boucle pour les wrappers claude -p lancés depuis un cron ou un script CI. Il s’exécute avant que le processus rende la main, ce qui le rend utile pour signaler la fin d’un run programmé, y compris quand le run échoue.

Les autres événements documentés (PreToolUse, PermissionRequest, TaskCompleted, SessionStart…) ont leur usage, mais pour une intégration Telegram simple, ces trois-là suffisent.

Le token de bot est un secret de production

Un token Telegram donne à quiconque le possède le pouvoir d’envoyer des messages comme votre bot.

Si votre bot est dans un groupe d’équipe, ou s’il sert aussi à recevoir des commandes, c’est plus que de la pollution : c’est un vecteur d’usurpation. Trois règles que je respecte sans exception :

Le token vit dans l’environnement, pas dans un fichier de config. ~/.zshenv ou un agent de secrets, pas ~/.claude/settings.json. Ce dernier est parfois synchronisé, parfois copié sur une seconde machine, parfois committé “juste pour cette branche”. Le script de hook lit $TELEGRAM_BOT_TOKEN ; le fichier versionné, lui, ne contient que le chemin du script.
Vérifiez le .gitignore avant chaque commit. Un grep -rE "bot[0-9]+:AA[A-Za-z0-9_-]+" . rattrape les fuites avant qu’elles arrivent sur GitHub. Les tokens Telegram ont une forme reconnaissable, exploitez-la.
Si le token a fuité, BotFather le révoque en une commande. /revoke propage en quelques secondes ; rebootez ensuite votre ~/.zshenv avec le nouveau token. La rotation est gratuite et le bot continue de répondre au même @handle.

C’est la même logique que pour tout autre secret qu’un agent peut lire : la question n’est pas “ce token va-t-il fuiter”, mais “le jour où il fuit, qu’est-ce que je perds”.

Ce que votre bot peut, et ne peut pas faire

Le bot par défaut envoie des messages. Point. Il ne lit pas votre disque, n’exécute pas de commandes, ne touche pas à votre repo. Le périmètre est minuscule, c’est précisément ce qui en fait une bonne automatisation, du même esprit que les petites boucles qui composent un trimestre.

Le piège est dans l’inverse. Si vous montez un bot qui reçoit des messages Telegram et lance des commandes claude depuis votre téléphone, la version “agent-from-phone”, vous venez d’exposer une console RCE par-dessus le protocole Telegram. Le token suffit alors à exécuter du code sur votre machine. À ce moment-là, il faut une liste blanche d’expéditeurs (from.id autorisés), un cooldown, un journal de ce qui a été exécuté, et l’acceptation que votre téléphone est désormais un terminal admin.

La version notifications-seulement, elle, est un excellent investissement. Vingt minutes à configurer, un signal au bon moment, aucun nouveau périmètre à défendre.

Si cela vous a parlé, vous aimerez La boucle d’agent qui a remplacé mon samedi et Secrets, outils, et l’agent qui a lu votre fichier env. Abonnez-vous ci-dessous pour recevoir le billet de vendredi prochain.