Самописные уведомления от Claude Code в Telegram / Хабр

Проблематика

Пока работал над флоу в статье, заметил, что некоторое количество просадок в производительности при работе с агентом вне режима авто-пилота возникает из-за тихих ожиданий. Например, ты не смотришь в IDE, читаешь что-то, а Claude Code сидит тебя ждет. Особенно это надоедает, когда агенту нужно какое-то разрешение.

Я люблю и практикую ChatOps. Поэтому решение пришло само: пусть агент мне пишет в телеге, когда я ему нужен.

Исследование

Сначала думал сунуть curl с коллбэком API телеги в CLAUDE.md, но:

Не секьюрно
Вряд ли будет работать. Или будет работать не всегда.

Еще думал обернуть нужное действие в skill, но тогда эта история неудобно масштабируема, громоздка и опять же, вряд ли заработает с конкретными событиями в цикле агента.

Пошел гуглить. Сначала попалась либа claude-code-telegram. Но для моей задачи это овер-скоуп.

Далее наткнулся на пост reddit, где предлагали добавить системный звук колокольчика, когда Claude завершает задачу.

Из этого поста я узнал про механизм hooks в .claude/settings.json.

Суть Hooks

На разных событиях агента можно завязать вызов bash-коллбэков. Вот полный список событий и их условий, переведенный на русский:

| Event              | Когда это срабатывает                                          |
| ------------------ | -------------------------------------------------------------- |
| SessionStart       | Когда сессия начинается или возобновляется                     |
| UserPromptSubmit   | Когда вы отправляете запрос, до того как Claude его обработает |
| PreToolUse         | До выполнения вызова инструмента. Может заблокировать его      |
| PermissionRequest  | Когда появляется диалог с запросом разрешения                  |
| PostToolUse        | После успешного выполнения вызова инструмента                  |
| PostToolUseFailure | После неудачного выполнения вызова инструмента                 |
| Notification       | Когда Claude Code отправляет уведомление                       |
| SubagentStart      | Когда порождается подагент                                     |
| SubagentStop       | Когда подагент завершает работу                                |
| Stop               | Когда Claude завершает ответ                                   |
| TeammateIdle       | Когда участник команды агентов собирается стать неактивным     |
| TaskCompleted      | Когда задача помечается как завершённая                        |
| PreCompact         | Перед сжатием контекста                                        |
| SessionEnd         | Когда сессия завершается                                       |

Дока и возможности хуков монструозные и далеко не ограничены вызовом curl.

Решение

Подвесить отправку мне в личку сообщений при событиях завершения задачи и запроса разрешний. Шаги:

Делаем себе бота в ТГ с помощью Bot Father
Копируем токен
Ищем бота и вызываем /start

Вызываем curl на Mac:

curl --location 'https://api.telegram.org/bot<BOT_TOKEN>/getUpdates'

Либо, если у вас Windows (далее примеры только с curl):

powershell -Command \"Invoke-RestMethod -Uri 'https://api.telegram.org/bot<BOT_TOKEN>/getUpdates'"

Из ответа берем ваш chat_id
Собираем curl на отправку сообщения по API подставив BOT_TOKEN и CHAT_ID. Код написан в строку и экранирован, чтобы дальше его вставить в JSON:
```
curl --location 'https://api.telegram.org/bot<BOT_TOKEN>/sendMessage' --header 'Content-Type: application/json' --data '{\"chat_id\": \"<CHAT_ID>\", \"text\": \"Claude ждет пермишшен.\"}
```
Открываем файл ~/.claude/settings.json
Добавляем коллбэки с вашим текстом сообщений на Stop (завершение задачи) и PermissionRequest(запрос разрешения):
```
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl --location 'https://api.telegram.org/bot<BOT_TOKEN>/sendMessage' --header 'Content-Type: application/json' --data '{\"chat_id\": \"<CHAT_ID>\", \"text\": \"✅ Задача завершена\"}'"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl --location 'https://api.telegram.org/bot<BOT_TOKEN>/sendMessage' --header 'Content-Type: application/json' --data '{\"chat_id\": \<CHAT_ID>\", \"text\": \"⚠️ Требуется твое действие\"}'"
          },
          {
            "type": "agent",
            "prompt": "Проверь результат выполнения задачи. Запомни его как <LAST_MESSAGE> не длиннее 200 символов. Затем выполни 'curl --location 'https://api.telegram.org/bot<BOT_TOKE>/sendMessage' --header 'Content-Type: application/json' --data '{\"chat_id\": \"<my_chat_id>\", \"text\": \"<last_message>\"}'"
          }
        ]
      }
    ]
  }
}
```
command вызывает баш-скрипт, отправлющий сообщение вам в личку. Так вы моментально поймете, что задача завершена или требует внимания.
agent вызывает суб-агента, который следом через пару секунд присылает вам отчет по проделанной работе. При этом взаимодействие с основным агентом не блокируется. В промпте я зашил сейф-гард на <= 200 символов, чтобы не получить отлуп от API телеги на длину сообщения.

Именно для доставки сообщений agentработает непредсказуемо. Может ничего не прислать. Если и использовать то точно после обычного вызова command с bash-скриптом. Если есть какой-то механизм перехвата stdout у Claude Code, чтобы передать уже нагенеренную по результату задачи информацию в command, я его не нагуглил.
Тестируем. Просим агента что-то сделать и мониторим телеграм:
Вы получите сообщение от агента с призывом к действию.
Когда агент завершит задачу, вы увидите, что начинают отрабатывать Stop хуки.
Следом вы получите два сообщения

Задача завершена
Краткую выжимку о проделанной работе

Итог

Так довольно просто можно сократить простои вашего агента и мониторить статус его работы вообще не будучи за компом. Сама механика хуков детерминирована и позволяет вам использовать кучу инструментов вашей операционной системы в пайплайне работы с агентом.

Обязательно посмотрите полную доку о хуках от Anthropic, что я указал в статье. Там тонна информации: на события можно вешать промпты, запреты инструментов, обработку ошибок, мониторинг и т. д. Пользуйтесь!