Инженерия · Агенты и MCP

Управление Claude Code из Telegram

Небольшой бот на Python превращает чат в телефоне в пульт для Claude Code на настольном компьютере: один headless-процесс на сообщение, хуки для уведомлений и подтверждений, параллельные слоты. Что мы построили за день и что узнали о запросах размером с экран телефона.

· 4 мин чтения

Долгие сессии агента плохо уживаются с работой за столом. Запускаешь задачу, она идёт двадцать минут, и ты либо сидишь и смотришь, либо уходишь и забываешь о ней. Нам нужно было обратное: начать работу с телефона, узнать, когда она закончится, подтвердить рискованный шаг откуда угодно и позже продолжить ту же сессию, просто ответив на сообщение. 21 октября 2026 года мы построили для этого небольшой Telegram-бот. Он работает на том же настольном компьютере с Windows, что и Claude Code.

Одно сообщение — один headless-процесс

Бот — это один файл на Python примерно на 1150 строк на python-telegram-bot 22.8 и два скрипта-хука. Долгоживущего агента в памяти он не держит. Каждое входящее сообщение запускает новый headless-процесс Claude Code, а непрерывность обеспечивается возобновлением сессии по ID:

claude -p --output-format stream-json --verbose \
  --append-system-prompt "<phone-specific instructions>" \
  --resume <session-id>          # omitted for a new conversation

Промпт передаётся через stdin. Бот читает поток JSON-событий построчно. Каждое событие tool_use превращается в короткий шаг вроде «🔧 Bash: run tests». Одно статусное сообщение в чате редактируется не чаще раза в три секунды и показывает прошедшие минуты и последние восемь шагов. Финальное событие result несёт ответ, ID сессии и стоимость, и бот учитывает стоимость по дням и по разговорам.

  1. СообщениеВ чат от разрешённого ID пользователя приходит текст, голосовое или файл.
  2. ЗапускБот запускает headless-процесс Claude Code в нужной папке и возобновляет сессию слота.
  3. ПотокВызовы инструментов из JSON-потока обновляют одно статусное сообщение живыми шагами.
  4. ОтветИтоговый ответ отправляется обратно вместе с файлами, которые агент пометил для отправки.
  5. ПродолжениеОтвет (reply) на любое сообщение бота возобновляет ту самую сессию в её исходной папке.
Рисунок 1

На телефоне всё это работает благодаря нескольким деталям:

  • Голос. Голосовые сообщения распознаются локально небольшой моделью Whisper на CPU. Промпт предупреждает агента, что в расшифровке могут быть ошибки распознавания.
  • Файлы в обе стороны. Входящие фото и документы сохраняются локально, их абсолютные пути добавляются в промпт. Чтобы отправить файл обратно, агент пишет в ответе строку [[SEND: <absolute path>]], и бот загружает этот файл.
  • Ответы под размер телефона. Дополнительный системный промпт просит отвечать кратко и без широких таблиц, а длинные ответы режутся на части под лимит сообщения Telegram.

Хуки: узнать о результате и сказать «да»

Самая полезная половина — не бот, а два хука Claude Code, которые работают и для сессий, начатых за клавиатурой.

Уведомления. Хук Stop присылает «готово» с именем проекта, длительностью и концом последнего ответа — но только если сессия шла дольше 30 секунд, чтобы быстрые вопросы не дёргали телефон. Хук Notification сообщает, когда Claude ждёт ввода или задаёт вопрос. Каждое отправленное сообщение связывается с ID своей сессии и рабочей папкой, поэтому ответ на уведомление возобновляет эту сессию прямо с телефона. Сессии, запущенные самим ботом, выставляют переменную окружения, которая заглушает хуки, так что ничего не приходит дважды.

Удалённые подтверждения. Блокирующий хук PermissionRequest отправляет ожидающее действие в чат с кнопками «Разрешить» и «Отклонить»: команду с её описанием или файл и diff правки. Хук ждёт файл, который бот записывает при нажатии кнопки, с таймаутом чуть меньше часа. Делает он это только тогда, когда пользователь «отошёл». В автоматическом режиме это значит, что 120 секунд не было ввода с клавиатуры или мыши. Если пользователь возвращается к столу, пока запрос висит, сообщение редактируется — запрос перешёл в терминал, и дальше всё решает запрос в терминале. Режим «отошёл» можно принудительно включить или выключить из чата.

Слоты: параллельная работа из одного чата

В первой версии на чат приходился один разговор, и это стало узким местом: долгий рефакторинг блокировал быстрый вопрос. Переписанная версия добавила слоты — до восьми параллельных разговоров на чат, у каждого свои название, ID сессии, папка и накопленная стоимость. Обычные сообщения идут в активный слот. Reply идёт в тот слот, которому принадлежит сообщение, на которое отвечают. Быстрые команды и запланированный утренний отчёт всегда открывают новый слот. При достижении лимита закрывается самый старый простаивающий слот. В тесте два параллельных слота с небольшой моделью оба завершились за 8,2 секунды.

Ещё два дополнения пришли из ежедневного использования:

  • Выбор сессии. /resume показывает прошлые сессии с читаемыми заголовками (сначала собственное название, затем сгенерированное ИИ, затем первый промпт), по восемь на страницу, а при выборе выводит последний ответ. Чтобы собрать заголовки, нужно читать файлы сессий. Кэш по пути и времени изменения сократил время с примерно 8 секунд в холодном состоянии до 0,02 секунды в тёплом на 186 сессиях.
  • Быстрые команды. Частые промпты лежат в JSON-файле из шести записей, и добавление новой — это правка JSON и перезапуск. Они же регистрируются как меню команд бота.

Уроки: побеждает самое простое толкование

Главный урок был не о коде, а о языке. Вначале сообщение вида «<путь к файлу> покажи» превратилось в 14-шаговую автоматизацию браузера, которая отрисовала файл и сделала скриншот, хотя просьба была просто «пришли мне этот файл». На телефоне ощущается каждый лишний шаг. Мы исправили это на двух уровнях. Во-первых, прямой путь: если сообщение — это путь к файлу и не больше двух слов, бот отправляет сам файл, не вызывая модель. Он находит и пути без расширения, и пути с распространёнными узбекскими суффиксами. Во-вторых, постоянная инструкция в системном промпте: «покажи» или «пришли» означает отправить сам файл сразу, и побеждает самое простое действие, удовлетворяющее запрос.

Другие уроки:

  • Читайте stderr параллельно. Первая версия читала stderr только после окончания stdout. Многословный процесс мог заполнить канал stderr и зависнуть. Решением стал параллельный читатель.
  • Перезапускайте дёшево. Batch-цикл поднимает бота через пять секунд после выхода, а запланированная задача скрыто запускает его при входе в систему. Перезапуск после изменения кода — это просто завершение процесса.
  • Не доверяйте определению бездействия вслепую. Внутри песочницы таймер бездействия однажды показал 47 часов. Ручной переключатель «отошёл» существует именно поэтому.

Ограничения

  • Граница доверия — список разрешённых и сама машина. Кто может пользоваться ботом, решает список разрешённых ID пользователей Telegram, и бот рассчитан лишь на личный компьютер, который вы контролируете: всё, что он запускает, имеет права пользователя этой машины.
  • Долгие задачи не переживают перезапуск. При перезапуске бота теряется связь с запущенными процессами, а таймаута на один запуск пока нет.
  • Форматирование. Сообщения отправляются простым текстом, поэтому Markdown от модели отображается как есть.
  • Одна машина. Бот управляет тем компьютером, на котором запущен. Это не размещённый сервис, и кроме приведённых выше цифр мы использование не измеряли.

Повторите сами

Бот — закрытый локальный проект; эти открытые команды показывают два кирпичика, на которых он построен: headless Claude Code с потоковым JSON и библиотеку Telegram-ботов.

$ pip install python-telegram-bot==22.8
$ claude -p --output-format stream-json --verbose "list the files in this folder"
Репозиторий
Репозиторий закрыт; команды используют только публичные инструменты.
Материалы
wonmortech/research

Источники

  1. claude-telegram-bot: bot.py, notify.py, perm_hook.py, commands.json (private, local project)
  2. Internal engineering notes, 2026-10-21 to 2026-10-22
  3. docs.python-telegram-bot.org/

Похожие материалы

Смотреть ещё