CCGram v4: Telegram에서 AI 코딩 에이전트 제어 — 이제 herdr 지원 포함

CCGram은 AI 코딩 에이전트를 위한 Telegram 브리지입니다. 각 Telegram 포럼 토픽은 Claude Code, Codex, Gemini, Pi 또는 일반 셸 (shell) 세션을 실행하는 터미널 멀티플렉서 (terminal multiplexer) 창과 1:1로 연결됩니다. 에이전트가 사용자의 컴퓨터에서 실행되는 동안, 사용자는 휴대폰에서 출력을 모니터링하고, 인라인 키보드 (inline keyboards)를 통해 대화형 프롬프트에 응답하며, 세션을 관리할 수 있습니다.

에이전트 프로세스는 사용자의 로컬 터미널 세션에 유지됩니다. 책상을 떠나더라도 Telegram을 통해 계속 작업할 수 있습니다. 다시 돌아와 터미널에 연결하면, 세션이 중단된 지점부터 정확히 이어지는 전체 스크롤백 (scrollback)을 확인할 수 있습니다.

v4.0.0은 완전한 herdr 백엔드 (backend) 지원을 제공합니다.

herdr란 무엇인가요?

herdr는 tmux와 유사하지만 세션과 창 대신 이름이 지정된 워크스페이스 (workspace)와 탭 (tab)을 중심으로 구성된 현대적인 터미널 멀티플렉서 (terminal multiplexer)입니다. 소켓 기반 (socket-based) 제어 API와 내장된 네이티브 에이전트 상태 보고 기능을 갖추고 있습니다.

herdr를 사용 중이며 ccgram이 이를 지원하기를 원한다면, 환경 변수 (environment variable) 하나를 설정하면 됩니다.

CCGRAM_MULTIPLEXER=herdr

토픽, 프로바이더 (providers), Claude 훅 (hooks), 세션 복구 (session recovery), 음성 메시지, 스크린샷, 라이브 뷰 등 나머지 모든 기능은 동일하게 작동합니다. 멀티플렉서는 코드베이스의 프로토콜 심 (Protocol seam) 뒤에 위치하므로, 호출자는 어떤 백엔드가 활성화되어 있는지 알 필요가 없습니다.

herdr 백엔드를 사용할 때 변경되는 점

적응형 토픽 레이블 (Adaptive topic labels)

tmux에서는 토픽이 창 이름을 상속받습니다. herdr에서는 토픽이 `

에이전트 탭만 토픽으로 노출됨

tmux에서는 모든 창이 Telegram 토픽이 될 자격이 있습니다. herdr에서는 에이전트 CLI (Claude Code, Codex, Gemini, Pi)를 활발하게 실행 중인 탭만 노출됩니다. 빈 셸(bare shell) 탭은 토픽이 되지 않습니다. 이는 herdr의 네이티브 에이전트 상태 (agent-status) 기능을 사용하며, 터미널 스크래핑 (terminal scraping)이 필요하지 않습니다.

네이티브 에이전트 상태 (Native agent status)

herdr는 pane process-info를 통해 팬(pane)에서 실행 중인 내용을 직접 보고합니다. ccgram은 활성 에이전트를 파악하기 위해 터미널 출력을 스크래핑할 필요가 없습니다. 대신 멀티플렉서 (multiplexer)가 이미 제공하는 구조화된 데이터를 읽습니다.

재시작 후 세션 재해결 (Session re-resolution after restart)

herdr는 서버가 재시작될 때 탭 ID를 다시 생성(re-mints)합니다. ccgram은 Claude 훅 (hook)에 의해 기록된 공유 세션 ID를 통해 오래된 탭 ID를 새로운 ID로 다시 매핑함으로써 이를 처리합니다. Telegram 토픽 바인딩 (bindings)은 herdr 재시작 후에도 유지됩니다.

프로토콜 버전 고정 (Protocol version pinning)

ccgram은 빌드 시 사용된 herdr 소켓 프로토콜 버전을 고정하며, 변경된 JSON 형태를 조용히 잘못 파싱하는 대신 버전 불일치 시 실행을 거부합니다.
herdr를 업그레이드한 후 프로토콜 에러가 발생한다면, ccgram 빌드를 버전에 맞춰 업데이트해야 합니다.

동일한 Claude Code 훅

세션을 추적하고 이벤트 (SessionStart, Stop, 대화형 UI 프롬프트)를 발생시키는 훅은 herdr의 경우 $HERDR_PANE_ID를, tmux의 경우 $TMUX_PANE를 사용하여 어떤 창에서 발생했는지 해결합니다. herdr 전용의 별도 훅 설정은 필요하지 않습니다.

아키텍처: 멀티플렉서 접점 (the multiplexer seam)

멀티플렉서 액세스는 multiplexer/base.py에 정의된 Multiplexer 프로토콜 뒤에 존재합니다. 이는 백엔드 임포트가 없는 순수하고 I/O가 없는 모듈입니다.
tmux (multiplexer/tmux.py)와 herdr (multiplexer/herdr.py) 모두 동일한 프로토콜을 구현하며 동일한 중립적 값 타입을 반환합니다:

• WindowRef — 창/탭 참조
• PaneInfo — 팬 메타데이터 (pane metadata)
• CaptureResult — 절단 플래그 (truncation flag)를 포함한 스크롤백 캡처
• ForegroundInfo — 포그라운드 프로세스 (pid, argv, cwd)

호출자(Callers)는 모듈 수준의 multiplexer 프록시(proxy)를 임포트하고 프로토콜(protocol)에 대해 타입을 지정하며, 구체적인 백엔드(concrete backend)를 직접 사용하지 않습니다. 아키텍처 적합성 테스트(tests/ccgram/test_multiplexer_boundary.py)를 통해 이러한 경계(boundary)를 강제합니다.

herdr를 이용한 빠른 시작

# ccgram 설치
uv tool install ccgram

...

Telegram 그룹을 열고, 새 토픽을 생성한 뒤 메시지를 보내면 디렉토리 브라우저(directory browser)가 나타납니다. 프로젝트 디렉토리를 선택하고, 에이전트(agent)를 선택하고, 워크스페이스(workspace)를 선택하면 연결이 완료됩니다.

설치

uv tool install ccgram          # 권장 사항
brew install alexei-led/tap/ccgram  # Homebrew (macOS)
pipx install ccgram             # pipx

릴리스 노트(Release notes): https://github.com/alexei-led/ccgram/releases/tag/v4.0.0
소스(Source): https://github.com/alexei-led/ccgram