CCBot: Telegram으로 Claude Code 세션을 원격 제어하는 혁신적인 접근

CCBot 데모

Claude Code는 터미널에서 실행되는 강력한 AI 코딩 도구입니다. 하지만 자리를 비우면 — 출근길, 소파에서, 혹은 단순히 책상을 떠나면 — 세션은 계속 돌아가지만 가시성과 제어권을 잃게 됩니다.

CCBot은 이 문제를 Telegram에서 동일한 세션을 seamlessly하게 이어가는 방식으로 해결합니다. 핵심은 Claude Code SDK가 아니라 tmux 위에서 동작한다는 점입니다.

1) 왜 CCBot의 접근이 특별할까

대부분의 Telegram 봇은 Claude Code SDK를 래핑해 별도의 API 세션을 생성합니다. 이 세션들은 격리되어 있어서 터미널에서 다시 이어갈 수 없습니다.

CCBot은 다른 접근을 취합니다:

일반적인 접근	CCBot의 접근
SDK 래핑 → 별도 세션	tmux 제어 → 기존 세션 유지
격리된 세션	터미널이 source of truth
터미널 복귀 불가	언제든 `tmux attach`로 복귀
단일 세션	여러 프로젝트 병렬 실행

핵심 인사이트: CCBot은 tmux 위에 얇은 제어 계층일 뿐입니다. 터미널이 여전히 진실의 원천이고, 언제든 완전한 scrollback과 컨텍스트로 돌아갈 수 있습니다.

2) 아키텍처 분석: tmux 기반 세션 관리

2.1 토픽 기반 1:1 매핑

CCBot은 Telegram Forum(토픽) 모드로 동작합니다.

1 Topic = 1 tmux Window = 1 Claude Session

각 Telegram 토픽은 하나의 tmux 윈도우에 매핑되고, 그 안에서 Claude Code가 실행됩니다. 이 구조의 장점:

멀티프로젝트 관리: 하나의 Telegram 그룹에서 여러 프로젝트 동시 진행
격리된 컨텍스트: 각 세션이 독립적인 대화 맥락 유지
간단한 세션 종료: 토픽을 닫으면 자동으로 tmux 윈도우 종료

2.2 Hook 기반 세션 추적

// ~/.claude/settings.json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{ "type": "command", "command": "ccbot hook", "timeout": 5 }]
      }
    ]
  }
}

SessionStart 훅이 session_map.json에 윈도우-세션 매핑을 기록합니다. /clear나 세션 재시작 후에도 어떤 Claude 세션이 어떤 tmux 윈도우에서 실행 중인지 자동으로 추적합니다.

3) 실시간 모니터링: 어떻게 동작할까

3.1 JSONL 폴링 방식

CCBot은 Claude Code의 세션 JSONL 파일을 2초마다 폴링합니다.

# session_monitor.py 핵심 로직
MONITOR_POLL_INTERVAL = 2.0  # seconds

# JSONL 파일에서 변경 감지 → 알림 생성

감지하는 이벤트:

이벤트 타입	설명
Assistant responses	Claude의 텍스트 응답
Thinking content	확장 가능한 blockquote로 표시
Tool use/result	”Read 42 lines”, “Found 5 matches” 등 요약
Local command output	`git status` 등의 stdout

3.2 터미널 파싱

# terminal_parser.py
# 터미널 pane을 파싱해 인터랙티브 UI와 상태 라인 감지

AskUserQuestion, ExitPlanMode, Permission Prompts 같은 인터랙티브 UI를 감지하고, Telegram inline keyboard로 사용자 입력을 받습니다.

4) 인터랙티브 UI 처리

CCBot은 단순한 메시지 전달을 넘어 양방향 인터랙션을 지원합니다.

4.1 권한 프롬프트 처리

┌─ Permission Required ─────────┐
│ Allow read of secrets.yaml?   │
│                               │
│ [✓ Allow] [✗ Deny] [⚠ Review]│
└───────────────────────────────┘

터미널에서 권한 요청이 오면 Telegram에서 inline 버튼으로 승인/거부할 수 있습니다.

4.2 AskUserQuestion 처리

Claude가 사용자 입력을 요청하면, Telegram에서 바로 응답할 수 있습니다.

4.3 슬래시 커맨드 포워딩

커맨드	동작
`/clear`	대화 기록 초기화
`/compact`	컨텍스트 압축
`/cost`	토큰/비용 확인
`/help`	Claude Code 도움말

인식되지 않는 /command도 그대로 Claude Code에 전달됩니다.

5) 음성 메시지와 스크린샷

5.1 음성→텍스트 변환

# transcribe.py
# OpenAI API로 음성 메시지를 텍스트로 변환

음성 메시지를 보내면 자동으로 텍스트로 변환되어 Claude Code에 전달됩니다. OpenAI API 키 설정이 필요합니다.

5.2 터미널 스크린샷

/screenshot 커맨드로 현재 터미널 상태를 PNG 이미지로 캡처합니다. ANSI 컬러를 지원하는 폰트 렌더링을 포함합니다.

6) 데이터 저장 구조

경로	설명
`$CCBOT_DIR/state.json`	토픽-윈도우 바인딩, read offset
`$CCBOT_DIR/session_map.json`	훅이 생성한 세션 매핑
`$CCBOT_DIR/monitor_state.json`	중복 알림 방지용 byte offset
`~/.claude/projects/`	Claude Code 세션 데이터 (읽기 전용)

7) 대안들과의 비교

축	CCBot	SDK 기반 봇	터미널만
원격 제어	✅ Telegram	✅ Telegram	❌
세션 연속성	✅ tmux 유지	❌ 격리	✅
멀티 세션	✅ 토픽별	제한적	✅ tmux 윈도우
인터랙티브 UI	✅ inline keyboard	제한적	✅ 직접 입력
음성 입력	✅ OpenAI 변환	구현 필요	❌

8) 실제 사용 시나리오

시나리오 1: 출근길 코드 리뷰

집에서 Claude Code로 리팩토링 진행 중
출근길에 Telegram에서 진행 상황 확인
Claude가 질문하면 inline 버튼으로 응답
회사 도착 후 tmux attach로 터미널 복귀

시나리오 2: 멀티 프로젝트 관리

토픽 A: 백엔드 API 작업
토픽 B: 프론트엔드 컴포넌트 작업
토픽 C: 문서화 작업
하나의 Telegram 그룹에서 모든 프로젝트 모니터링

마치며: 오픈소스 에이전트 제어의 새로운 패턴

CCBot은 Claude Code SDK를 래핑하지 않고, tmux라는 검증된 도구 위에 제어 계층을 얹었습니다. 이 접근의 아름다움은:

“기존 워크플로우를 깨지 않으면서, 어디서든 접근 가능하게 만들었다.”

이 패턴은 다른 CLI 도구에도 적용할 수 있습니다. tmux + 메신저 봇 조합은 원격 제어의 일반화된 솔루션이 될 수 있습니다.

CCBot 자체도 이 방식으로 개발되었다고 합니다 — CCBot을 통해 CCBot을 개발하는 셀프 호스팅 사이클. 이것이 가능한 아키텍처라는 게 가장 큰 증명입니다.

🔗 관련 정보

GitHub: https://github.com/six-ddc/ccbot
Claude Code Docs: https://docs.anthropic.com/en/docs/claude-code
tmux Manual: https://man7.org/linux/man-pages/man1/tmux.1.html
Telegram Bot API: https://core.telegram.org/bots/api