CCGram: 텔레그램으로 AI 코딩 에이전트를 원격 제어하는 오픈소스 도구

실용적 조언

uv tool install ccgram 명령어로 빠르게 설치하여 사용해 볼 수 있다.
Claude Code를 주력으로 사용한다면 ccgram hook --install 명령어를 통해 실시간 알림 기능을 활성화하는 것이 좋다.
텔레그램 그룹에서 '주제(Topics)' 기능을 활성화해야 각 에이전트 세션을 독립된 토픽으로 관리할 수 있다.

섹션별 상세

CCGram은 로컬 머신의 tmux 윈도우에서 실행되는 에이전트의 출력을 읽어 텔레그램 포럼 토픽으로 전달하는 브릿지 역할을 수행한다. 사용자가 텔레그램에서 메시지를 보내면 해당 키스트로크가 에이전트에게 직접 전달되어 모바일에서도 대화형 세션을 유지할 수 있다. 노트북을 닫고 이동하더라도 텔레그램을 통해 작업을 지속하다가 나중에 다시 tmux에 접속하면 전체 스크롤백이 그대로 보존된다.

Claude Code와의 깊은 통합을 위해 7가지 훅 이벤트(세션 시작, 알림, 중단, 서브에이전트 상태 등)를 지원한다. 이를 통해 단순한 텍스트 폴링이 아닌 실시간 세션 추적과 알림이 가능하며, 사용자 질문이나 권한 요청 같은 대화형 프롬프트는 텔레그램 인라인 키보드 버튼으로 렌더링되어 탭 한 번으로 승인 처리가 가능하다.

멀티 프로바이더 및 멀티 세션 관리를 지원하여 Claude Code, Codex CLI, Gemini CLI를 각기 다른 텔레그램 토픽에서 병렬로 실행할 수 있다. 각 프로바이더의 특성을 인식하여 새로 시작하거나 기존 세션을 재개하는 버튼이 동적으로 적응하며, Gemini의 경우 작업 중이거나 조치가 필요한 상태를 자동으로 감지하여 표시한다.

bash

ccgram hook --install

Claude Code와의 최적 연동을 위해 훅 시스템을 설치하는 명령어

CCGram 프로젝트 자체가 Claude Code를 사용하여 개발되었다는 점이 특징이다. 아키텍처 설계부터 프로바이더 추상화, VT100 터미널 파서 구현, 대화형 UI 렌더링, E2E 테스트 하네스 구축까지 모든 과정에 Claude Code가 활용되었으며, 이는 AI 코딩 에이전트가 스스로를 제어하는 도구를 직접 만든 사례이다.

용어 해설

터미널 멀티플렉서(tmux): — 단일 터미널 창에서 여러 개의 가상 터미널 세션을 생성하고 관리할 수 있게 해주는 도구이다. 세션을 백그라운드에서 유지할 수 있어 원격 접속이 끊겨도 작업이 중단되지 않으며, 나중에 다시 연결하여 이전 상태를 그대로 유지하는 기능이 핵심이다.
VT100 터미널 표준(VT100): — 텍스트 기반 터미널에서 색상, 커서 위치, 화면 지우기 등을 제어하기 위한 제어 시퀀스 표준이다. 현대의 터미널 에뮬레이터들도 이 표준을 기반으로 작동하며, 텍스트 인터페이스에서 복잡한 UI를 렌더링하는 데 필수적인 역할을 한다.
훅 이벤트(Hook Event): — 특정 소프트웨어 시스템에서 사건이 발생했을 때 외부 프로그램이 이를 감지하고 반응할 수 있도록 설계된 인터페이스이다. 폴링 방식과 달리 사건 발생 즉시 알림을 전달받으므로 실시간 상태 추적과 자동화된 워크플로 구축에 매우 중요하다.
마크다운 V2(MarkdownV2): — 텔레그램 메신저에서 지원하는 텍스트 서식 지정 방식의 최신 버전이다. 굵게, 기울임, 코드 블록, 인라인 링크 등 다양한 서식을 지원하여 봇이 사용자에게 가독성 높은 기술 정보를 전달할 때 주로 활용된다.

코드 예제

bash

uv tool install ccgram
# 또는
brew install alexei-led/tap/ccgram

CCGram 도구를 설치하는 명령어

언급된 도구

CCGram추천링크

tmux와 텔레그램을 연결하는 AI 에이전트 원격 제어 브릿지

Claude Code추천

Anthropic에서 개발한 CLI 기반 자율 코딩 에이전트

tmux추천

터미널 세션 유지 및 멀티플렉싱 도구

언급된 리소스

GitHubCCGram GitHub Repository