Claude Code Telegram Kit

Не очередной Telegram-мост. Официальный канал Claude Code от Anthropic остаётся входящим. Этот набор исправляет две вещи, которые он не делает: Markdown, который выдерживает парсер Telegram, и сброс контекста с телефона.

Инфраструктура исследовательской предварительной версии. Ознакомьтесь с моделью безопасности перед подключением к машине с ценными данными.

Один и тот же Markdown-документ, оба пути. Официальный инструмент reply по умолчанию использует format: "text", поэтому разметка приходит буквально; его режим markdownv2 перекладывает экранирование MarkdownV2 на модель, где один пропущенный символ приводит к сбою отправки. send_reply принимает документ без экранирования и сам выбирает транспорт. (Изображения отображаются с обоих путей, а не скриншоты устройств.)

Зачем это нужно

Любой другой проект «Claude Code + Telegram» заменяет официальный канал: свой собственный опросчик, своё управление сессиями, свою привязку. Этот — нет. Входящий опрос, привязка отправителя, вложения и ретрансляция разрешений остаются за плагином Anthropic. Набор добавляет две ограниченные возможности исходящего/управления рядом с ним, без второго потребителя getUpdates:

• Telegram Renderer MCP — один канонический инструмент send_reply(raw Markdown) с детерминированной маршрутизацией Rich Message vs MarkdownV2 и откатом только при постоянной ошибке.

• Session Control MCP — путь /reset с одобрением, поддерживаемый локальным помощником сброса, принадлежащим root, с закрытым отказом, который выполняет PID 1.

Оба пробела открыты в вышестоящем проекте. Этот набор — временное решение:

• anthropics/claude-code#39684 — нет способа очистить или сбросить контекст удалённо

• anthropics/claude-code#36622 и claude-plugins-official#774 — запрос MarkdownV2 parse_mode

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

Требуется официальный плагин telegram@claude-plugins-official, уже сопряжённый и работающий.

git clone https://github.com/project-tharsis/claude-code-telegram-kit
cd claude-code-telegram-kit
bun install --frozen-lockfile
bun run check

sha=$(git rev-parse HEAD)
python3 scripts/deploy_local.py install --repo . --ref "$sha" --bun "$(command -v bun)"

Затем скопируйте examples/.mcp.json, examples/telegram-settings.json и examples/CLAUDE.md в свой проект Claude, заменив USER на свои пути. Отправьте сообщение с таблицей GFM; рендерер должен сообщить mode: rich.

Рендерер работает сам по себе. /reset дополнительно требует корневого помощника, установленного отдельно по процедуре точного коммита в README session-control.

Для развёртывания в производственной среде, отката и проверки следуйте операционному руководству, а не этому разделу.

Архитектура

Telegram
  -> telegram@claude-plugins-official     # sole inbound poller
  -> Claude Code
     -> telegram-renderer MCP              # bounded outbound rendering
     -> session-control MCP                # bounded reset scheduling
        -> systemd transient unit
        -> root-owned session reset helper

Рендерер и управляющие MCP повторно используют токен официального канала и полномочия access.json. Они требуют dmPolicy: allowlist, безопасные файлы состояния с правами 0600 и точное членство в назначении.

Инварианты проектирования

Эти пять определяют радиус поражения:

• Один потребитель getUpdates Telegram на токен бота.

• Нет инструмента произвольного метода Bot API.

• Нет инструмента произвольной команды оболочки.

• Тайм-ауты, ответы 429, 5xx и неизвестные результаты никогда не вызывают повторную отправку.

• PID 1 владеет выполнением сброса до завершения процесса Claude.

Полный набор находится в docs/design-invariants.md.

Структура репозитория

packages/
  shared/                  Telegram authority validation
  telegram-renderer-mcp/   Markdown renderer and MCP server
  session-control-mcp/     Reset controller, MCP server, root helper
examples/                  Generic Claude, MCP, systemd, and reset config
scripts/                   Versioned local install and rollback

Требования

• Linux с systemd и procfs, смонтированным в /proc

• Claude Code 2.1.234 или новее

• Bun 1.3.14 или новее

• Python 3.11 или новее

• Официальный плагин Anthropic telegram@claude-plugins-official

Модель установки

Не запускайте производственную среду из изменяемой рабочей копии разработки. Установите точный коммит в каталог версионированного релиза:

~/.local/share/claude-code-telegram-kit/
  releases/<git-sha>/
  current -> releases/<git-sha>
  previous -> releases/<previous-sha>

scripts/deploy_local.py извлекает Git-архив с помощью экстрактора без ссылок/обхода, совместимого с Python 3.11, устанавливает производственные зависимости, проверяет квитанцию релиза и атомарно заменяет current/previous. Он никогда не устанавливает файлы, принадлежащие root.

python3 scripts/deploy_local.py status
python3 scripts/deploy_local.py rollback

Храните учётные данные Telegram и списки разрешений в каталоге состояния Claude, а конфигурацию сброса, принадлежащую root, храните в /etc/claude-code-telegram-kit/.

Сброс сессии

Локальный орган восстановления:

sudo claude-code-session-reset --config /etc/claude-code-telegram-kit/reset.json

Необязательная команда Telegram /reset — это тонкий интерфейс MCP. Она не может восстановить процесс Claude, который уже не может получать сообщения; держите локальный помощник доступным как аварийный путь.

Разработка

bun install --frozen-lockfile
bun run check
bun audit

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

Прочтите SECURITY.md перед развёртыванием. Никогда не фиксируйте токены ботов, ID чатов, стенограммы, пути, специфичные для сервиса, или конфигурацию активного сброса.

Статус проекта

Код извлечён из живого, проверенного развёртывания, затем обобщён в публичный репозиторий, созданный в условиях чистой комнаты. API могут измениться до 1.0.0.

Первоначальный релиз только в исходном коде. Пакеты рабочей области помечены как private и не публикуются в npm; устанавливайте из точного Git-коммита с помощью скрипта развёртывания с версиями.

Лицензия

Apache-2.0. См. LICENSE, NOTICE и THIRD_PARTY_NOTICES.md. Процедура релиза: RELEASING.md.

Этот проект независим и не одобрен Anthropic или Telegram.