telegram-bridge

telegram-bridge for Claude Code

Telegram-агент для Claude Code: Claude пишет тебе в Telegram, когда задача закончена, и может принимать ответы из Telegram, пока ты отошел от терминала.

Что получится после установки:

• Claude сможет отправлять тебе сообщения, файлы и скриншоты в Telegram.
• Ты сможешь отвечать Claude прямо в Telegram.
• Несколько Claude Code сессий смогут пользоваться одним ботом.
• Никакого сервера, демона и внешней базы. Только Telegram bot token и один Python-скрипт.

Быстрый старт

Нужно примерно 5 минут.

1. Установи плагин

В Claude Code выполни:

/plugin marketplace add azalio/claude-telegram-skill
/plugin install telegram-bridge@azalio

2. Создай Telegram-бота

Открой @BotFather в Telegram.

Отправь:

/newbot

BotFather попросит имя и username бота, потом выдаст token вида:

123456789:AA...

3. Создай конфиг

В терминале выполни:

mkdir -p ~/.claude/telegram
nano ~/.claude/telegram/config.json

Вставь туда JSON и замени PUT_YOUR_BOT_TOKEN_HERE на token от BotFather:

{
  "token": "PUT_YOUR_BOT_TOKEN_HERE",
  "chat_id": null,
  "user_id": null,
  "idle_mirror_secs": 600,
  "always_listen": true
}

Сохрани файл.

4. Перезапусти Claude Code сессию

Закрой текущую Claude Code сессию и открой новую.

После старта плагин создаст удобную команду:

~/.claude/telegram/tg

5. Напиши боту первым

Открой своего нового бота в Telegram и отправь ему любое сообщение, например:

/start

Это обязательно: Telegram не отдаст chat_id и user_id, пока ты сам не написал боту.

6. Заверши настройку

В терминале выполни:

~/.claude/telegram/tg setup

Должно появиться что-то вроде:

chat_id set to 123456789, user_id 123456789

Готово.

Проверь отправку:

~/.claude/telegram/tg send "test from Claude Code"

Как пользоваться

Самый простой способ: просто проси Claude писать тебе в Telegram.

Примеры промптов:

Сделай задачу и напиши мне в Telegram, когда закончишь.

Запусти тесты, исправь ошибки и пришли результат в Telegram.

Если понадобится мой ответ, спроси меня в Telegram.

Сделай исследование, а итоговый markdown-файл отправь мне в Telegram.

Как писать Claude из Telegram

Когда новая Claude Code сессия стартует, бот пришлет сообщение вида:

Сессия на связи: project-name

Чтобы написать именно этой сессии, отвечай в Telegram реплаем на это сообщение или на любое сообщение этой сессии.

Важно: обычное сообщение без reply не будет доставлено ни в какую сессию. Это сделано специально, чтобы один бот не отправил команду не тому Claude-процессу.

Что умеет команда tg

После установки доступна команда:

~/.claude/telegram/tg <command>

Основные команды:

Команда	Что делает
send "text"	Отправить текст в Telegram
send -	Прочитать текст из stdin и отправить
file <path> [caption]	Отправить файл
photo <path> [caption]	Отправить картинку
setup	Автоматически записать chat_id и user_id в конфиг
listen [seconds]	Ждать сообщение из Telegram для текущей сессии
ask "text" [seconds]	Отправить вопрос и ждать ответ
drain	Сбросить offset и очистить inbox

Примеры:

~/.claude/telegram/tg send "Готово, тесты прошли"
~/.claude/telegram/tg file report.md "Отчет"
~/.claude/telegram/tg photo screenshot.png "Скриншот"

Как это работает

Плагин состоит из одного Python-скрипта scripts/tg.py и Claude Code hooks.

Hooks подключены на события:

• SessionStart: создает launcher ~/.claude/telegram/tg и объявляет сессию в Telegram.
• Stop: может отправить последнее сообщение в Telegram, если ты долго не отвечаешь в терминале.
• UserPromptSubmit: отменяет idle-mirror, когда ты вернулся в терминал.
• Notification: отправляет Telegram-уведомление, если Claude ждет твоего ввода.

Состояние хранится здесь:

~/.claude/telegram/

Там лежат config, offset, inbox, locks и routing map. В репозитории токен не хранится.

Безопасность

Плагин принимает входящие Telegram-сообщения только от user_id, который записан в ~/.claude/telegram/config.json.

Это значит:

• Если кто-то найдет твоего бота, он не сможет управлять Claude без твоего Telegram user id.
• Если у тебя несколько Claude Code сессий, сообщение доставляется только той сессии, на сообщение которой ты ответил reply.
• Сообщения без reply не угадываются и не рассылаются всем сессиям.

Никогда не коммить свой ~/.claude/telegram/config.json и не публикуй bot token.

Настройки

Файл настроек:

~/.claude/telegram/config.json

Поля: