Claude Code Telegram Kit

또 다른 텔레그램 브리지가 아닙니다. Anthropic의 공식 Claude Code Channel은 인바운드만 처리합니다. 이 키트는 Claude Code Channel이 하지 못하는 두 가지, 즉 텔레그램 파서를 통과하는 마크다운과 휴대폰에서 컨텍스트를 재설정하는 기능을 제공합니다.

연구-프리뷰 인프라입니다. 중요한 데이터가 있는 머신에 연결하기 전에 보안 모델을 검토하세요.

동일한 마크다운 문서, 두 가지 경로입니다. 공식 reply 도구는 기본적으로 format: "text"를 사용하므로 마크업이 그대로 전달됩니다. markdownv2 모드는 MarkdownV2 이스케이프 처리를 모델에 넘기는데, 하나라도 빠지면 전송이 실패합니다. send_reply는 문서를 이스케이프하지 않고 가져와 전송 방식을 자체적으로 선택합니다. (그림은 두 경로 모두에서 렌더링된 결과이며, 기기 스크린샷이 아닙니다.)

Why this exists

다른 모든 "Claude Code + Telegram" 프로젝트는 공식 Channel을 대체합니다. 자체 폴러, 자체 세션 관리, 자체 페어링을 사용합니다. 이 키트는 그렇게 하지 않습니다. 인바운드 폴링, 발신자 페어링, 첨부 파일, 권한 중계는 모두 Anthropic의 플러그인에 맡깁니다. 이 키트는 두 개의 제한된 아웃바운드/제어 기능을 그 옆에 추가하며, 두 번째 getUpdates 소비자를 사용하지 않습니다.

• Telegram Renderer MCP — 결정론적 Rich Message vs MarkdownV2 라우팅과 영구 실패 시에만 폴백을 사용하는 하나의 표준 send_reply(raw Markdown) 도구입니다.

• Session Control MCP — 승인 게이트가 있는 /reset 경로로, PID 1이 실행하는 루트 소유의 fail-closed 로컬 재설정 헬퍼를 기반으로 합니다.

두 가지 격차 모두 상류에서 열려 있습니다. 이 키트는 그 사이의 임시 해결책입니다.

• anthropics/claude-code#39684 — 원격에서 컨텍스트를 지우거나 재설정할 방법이 없음

• anthropics/claude-code#36622 및 claude-plugins-official#774 — MarkdownV2 parse_mode 요청

Quickstart

공식 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를 클로드 프로젝트에 복사하고 USER를 자신의 경로로 바꾸세요. GFM 테이블이 포함된 메시지를 보내면 렌더러가 mode: rich를 보고해야 합니다.

렌더러는 단독으로 작동합니다. /reset은 추가로 루트 헬퍼가 필요하며, session-control README의 정확한 커밋 절차에 따라 별도로 설치해야 합니다.

프로덕션 배포, 롤백, 검증을 위해서는 이 섹션이 아닌 operations runbook을 따르세요.

Architecture

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는 공식 Channel의 토큰과 access.json 권한을 재사용합니다. dmPolicy: allowlist, 보안 0600 상태 파일, 정확한 대상 멤버십이 필요합니다.

Design invariants

다음 다섯 가지가 블래스트 반경을 정의합니다.

• 봇 토큰당 하나의 Telegram getUpdates 소비자.

• 임의의 Bot API 메서드 도구 없음.

• 임의의 셸 명령 도구 없음.

• 타임아웃, 429, 5xx 응답, 알 수 없는 결과는 재전송을 트리거하지 않음.

• PID 1이 클로드 프로세스가 종료되기 전에 재설정 실행을 소유함.

전체 목록은 docs/design-invariants.md에 있습니다.

Repository layout

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

Requirements

• Linux with systemd and procfs mounted at /proc

• Claude Code 2.1.234 or newer

• Bun 1.3.14 or newer

• Python 3.11 or newer

• Anthropic's official telegram@claude-plugins-official plugin

Installation model

변경 가능한 개발 체크아웃에서 프로덕션을 실행하지 마세요. 정확한 커밋을 버전이 지정된 릴리스 디렉터리에 설치하세요.

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

scripts/deploy_local.py는 Python 3.11 호환 no-link/no-traversal 추출기로 Git 아카이브를 추출하고, 프로덕션 종속성을 설치하며, 릴리스 영수증을 확인하고, current/previous를 원자적으로 교체합니다. 루트 소유 파일을 설치하지 않습니다.

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

텔레그램 자격 증명과 허용 목록은 클로드의 상태 디렉터리에, 재설정 구성은 루트 소유로 /etc/claude-code-telegram-kit/에 유지하세요.

Session reset

로컬 복구 권한은 다음과 같습니다.

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

선택적 Telegram /reset 명령은 얇은 MCP 프론트엔드입니다. 이미 메시지를 수신할 수 없는 클로드 프로세스를 복구할 수 없습니다. 비상 경로로 로컬 헬퍼를 사용 가능하게 유지하세요.

Development

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

Security

배포 전에 SECURITY.md를 읽으세요. 봇 토큰, 채팅 ID, 대화 내용, 서비스별 경로, 라이브 재설정 구성을 커밋하지 마세요.

Project status

이 코드는 라이브 검증된 배포에서 추출된 후 클린룸 공개 저장소로 일반화되었습니다. 1.0.0 이전에는 API가 변경될 수 있습니다.

초기 릴리스는 소스 전용입니다. 워크스페이스 패키지는 private으로 표시되어 있으며 npm에 게시되지 않습니다. 버전이 지정된 배포 스크립트로 정확한 Git 커밋에서 설치하세요.

License

Apache-2.0. LICENSE, NOTICE, THIRD_PARTY_NOTICES.md를 참조하세요. 릴리스 절차: RELEASING.md.

이 프로젝트는 독립적이며 Anthropic 또는 Telegram의 보증을 받지 않습니다.