Claude Code Telegram Kit

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

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

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

존재 이유

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

• Telegram Renderer MCP — 결정론적 Rich Message vs MarkdownV2 라우팅, 영구 전용 폴백, 👀 → 👍/👎 처리 반응을 갖춘 하나의 표준 send_reply(raw Markdown) 도구입니다.

• Session Control MCP — 승인 게이트가 있는 /reset 경로로, 확인된 수락 반응을 최종 확정한 후 PID 1이 실행하는 루트 소유의 폐쇄-실패 로컬 리셋 헬퍼로 실행을 넘깁니다.

두 가지 격차 모두 업스트림에서 열려 있습니다. 이 키트는 임시 해결책입니다:

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

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

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을 공식 Channel의 access.json에 병합하여 초기 👀 확인을 활성화하세요. GFM 테이블이 포함된 메시지를 보내세요. 렌더러가 mode: rich를 보고하고 👀를 👍로 바꿔야 합니다.

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

프로덕션 배포, 롤백 및 검증을 위해서는 이 섹션 대신 운영 런북을 따르세요.

아키텍처

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 상태 파일 및 정확한 대상 멤버십이 필요합니다.

설계 불변성

다음 다섯 가지가 피해 범위를 정의합니다:

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

• 임의의 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

요구 사항

• systemd 및 /proc에 마운트된 procfs를 갖춘 Linux

• 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는 Python 3.11 호환 링크 없음/트래버설 없음 추출기로 Git 아카이브를 추출하고, 프로덕션 종속성을 설치하며, 릴리스 영수증을 확인하고, current/previous를 원자적으로 교체합니다. 루트 소유 파일을 설치하지 않습니다.

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

Telegram 자격 증명 및 허용 목록은 Claude의 상태 디렉토리 아래에 유지하고, 리셋 구성은 /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, 대화 내용, 서비스별 경로 또는 실시간 리셋 구성을 절대 커밋하지 마세요.

프로젝트 상태

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

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

라이선스

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

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