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 с подтверждением, который финализирует подтвержденную реакцию принятия, а затем передает выполнение корневому, закрытому при сбое локальному помощнику сброса, который выполняет PID 1.

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

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

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

Related MCP server: tsgram-mcp

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

Требуется, чтобы официальный плагин 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 на свои пути. Объедините examples/access-ux.json с access.json официального канала, чтобы включить первоначальное подтверждение 👀. Отправьте сообщение с таблицей 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.