Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
CCGram은 Telegram을 통해 터미널 멀티플렉서(tmux 등)와 연결하여 AI 코딩 에이전트를 원격 제어할 수 있게 해주는 도구입니다. Claude Code, Codex CLI 등 다양한 에이전트를 모바일에서 모니터링하고 프롬프트를 입력하며 세션을 관리할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Coding Assistants의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기휴대전화로 AI 코딩 에이전트(AI coding agents)를 제어하세요. CCGram은 Telegram을 사용자의 터미널 멀티플렉서(terminal multiplexer, 기본값은 tmux, 또는 herdr)와 연결합니다. 컴퓨터를 만지지 않고도 출력을 모니터링하고, 프롬프트(prompts)에 응답하며, 여러 세션을 관리할 수 있습니다. Claude Code, Codex CLI, Gemini CLI, Pi 및 일반 셸(shell) 세션을 지원합니다.
AI 코딩 에이전트(AI coding agents)는 터미널에서 실행됩니다. 출퇴근 중이거나, 소파에 있거나, 혹은 단순히 책상을 떠나 있을 때 세션은 계속 작동하지만, 가시성과 제어력을 잃게 됩니다.
CCGram은 이 문제를 해결합니다. 이 도구는 특정 에이전트 SDK가 아닌 터미널 멀티플렉서(terminal multiplexer) 위에서 작동합니다. 에이전트 프로세스는 사용자의 머신에 있는 멀티플렉서 창 내의 원래 위치에 그대로 유지됩니다. CCGram은 해당 출력을 읽고 키 입력(keystrokes)을 전달합니다. 이는 다음을 의미합니다:
대화 도중 데스크톱에서 휴대전화로— 자리를 떠나더라도 Telegram을 통해 계속 모니터링할 수 있습니다.
언제든 휴대전화에서 데스크톱으로— 터미널 세션에 다시 연결(attach)하면 전체 스크롤백(scrollback)과 함께 복귀할 수 있습니다.
병렬 다중 세션— 각 Telegram 토픽(topic)은 별도의 창에 매핑되며, 각 창에서 서로 다른 에이전트가 실행됩니다.
다른 Telegram 봇들은 에이전트 SDK를 터미널에서 재개할 수 없는 격리된 API 세션으로 래핑(wrap)합니다. 반면, CCGram은 터미널 멀티플렉서(terminal multiplexer) 위의 얇은 제어 계층(control layer)입니다. 즉, 터미널이 신뢰할 수 있는 단일 원천(source of truth)으로 유지됩니다.
graph LR
subgraph phone["📱 Telegram Group (Forum Topics)"]
direction TB
...
각 Telegram 포럼(Forum) 토픽은 하나의 멀티플렉서 창에 바인딩됩니다. 사용자가 입력하는 메시지는 해당 창(pane)으로 키 입력(keystrokes)으로 전송되며, 응답은 세션 트랜스크립트(session transcripts)에서 파싱되어 Telegram 메시지로 다시 전달됩니다.
에이전트당 하나의 토픽— 각 Telegram 포럼(Forum) 토픽은 하나의 에이전트 CLI를 실행하는 하나의 멀티플렉서 창입니다.
Git 워크트리(worktree) 토픽— 새로운 토픽의 디렉토리가 적절한 git 저장소인 경우, 새로운 브랜치(권장 형식: ccg/<topic-title>)의 새로운 워크트리(worktree)에서 에이전트를 실행할 수 있습니다.
, 현재 브랜치 대신 다른 브랜치로 전환(원탭 확인 또는 이름 편집 가능); non-git 디렉토리는 변경되지 않은 흐름을 유지합니다.대화형 프롬프트 (Interactive prompts)— AskUserQuestion, ExitPlanMode, 그리고 인라인 키보드로 렌더링되는 권한(Permission) 대화 상자슬래시 명령어 (Slash commands)— 프로바이더 인식 메뉴 (Claude /cost, Codex /status, Gemini /chat, Pi /new, /compact, /scoped_models 등); Pi는 또한 Pi의 Alt+Enter 후속 메시지를 대기열에 추가하기 위한 /followup <message>를 지원합니다; 일치하지 않는 명령어는 오류를 보고합니다음성 메시지 (Voice messages)— Whisper API (OpenAI/Groq)를 통해 전사되며, 전달하기 전에 보내기 / 버리기 (Send / Discard) 버튼과 함께 표시됩니다멀티 페인 지원 (Multi-pane support)— 에이전트 팀 내에서 차단된 페인을 자동 감지하고, 프롬프트를 알림으로 표시합니다; 개요를 보려면 /panes를 사용하세요터미널 스크린샷 (Terminal screenshots)— 현재 뷰포트를 ANSI 색상이 포함된 읽기 가능한 PNG로 현재 페인(또는 특정 페인)을 캡처합니다마지막 답변 (Last reply) (/last, 📄Last 버튼) — 가장 최근의 어시스턴트 답변(트랜스크립트로부터의 AI 프로바이더 답변) 또는 마지막 명령어+출력(쉘 주제)을 다시 보냅니다; 긴 응답은 거대한 이미지 대신 .txt 첨부 파일로 넘칩니다터미널 라이브 뷰 (Terminal live view)— Live 버튼 또는 /live 명령어를 통해 5초마다 스크린샷을 자동 새로고침합니다; 콘텐츠 해시 게이팅(content-hash gating)을 통해 변경 사항이 없을 때는 편집을 건너뜁니다; 타임아웃 후 자동 중지됩니다(설정 가능)파일 전송 (File delivery) (/send) — 워크스페이스 파일을 Telegram으로 전송합니다: 정확한 경로 (/send docs/arch.png), 글로브 패턴 (/send *.png), 부분 문자열 검색 (/send arch), 또는 대화형 브라우저 (/send). 보안 필터링(숨겨진 파일, 자격 증명, gitignored, 50MB 초과 파일 거부)이 적용된 프로젝트 범위 내에서 작동합니다액션 툴바 (Action toolbar) (/toolbar
)— provider별 인라인 버튼입니다. 첫 번째 행은 범용적(Screenshot, Ctrl-C, Live)이며, 두 번째 행은 제공자마다 다릅니다: Claude (Mode, Think, Esc), Codex (Esc, Tab, Mode), Gemini (Mode, YOLO, Esc), Pi (Esc, Tab, π Model), Shell (Enter, EOF, Suspend). Claude/Codex/Gemini/Pi는 범용 탐색 행(Up, Enter, Down)을 추가합니다. 마지막 행은 Last, Get File, Close입니다 (Shell은 Esc를 포함하여 폴딩: Last, Get File, Esc, Close). ~/.ccgram/toolbar.toml에서 사용자 정의할 수 있습니다.
Picker 힌트(Picker hints)— TUI 피커에서 모달을 여는 슬래시 명령어(예: /model, /login, /theme)를 포워딩하면, 토픽 답글은 화살표 키로 피커를 구동하기 위해 /toolbar 사용을 제안합니다.
원격 제어(Remote Control)— RC가 활성화되면 📡 토픽 배지가 표시됩니다. 에이전트에게 /remote-control (또는 /rc)을 포워딩하여 활성화할 수 있습니다. Claude의 /remote-control은 결과에 대해 침묵하므로, ccgram은 나중에 해당 창(pane)을 조사하고 그 결과를 단일 상태 답글로 게시합니다 (성공 시 공유 URL,
또는 실패 메시지). Hook 이벤트 (Stop, errors, subagent updates)는 게이트를 우회합니다. 엔티티 기반 포맷팅 (Entity-based formatting) — 마크다운(markdown)을 일반 텍스트(plain text)로 변환 + MessageEntity 오프셋(offsets) 적용; 자동 일반 텍스트 폴백(fallback) 지원으로 파싱 에러(parse errors) 방지
디렉토리 브라우저 (Directory browser) — 파일 시스템을 탐색하여 텔레그램(Telegram)에서 세션 생성
자동 동기화 (Auto-sync) — 멀티플렉서(multiplexer) 창을 수동으로 생성하면 봇이 자동으로 일치하는 토픽을 생성
복구 (Recovery) — 세션이 종료될 경우 키보드(keyboard)를 통해 새로 고침(Fresh) / 계속(Continue) / 재개(Resume) 선택 가능 (버튼은 제공자(provider)에 따라 적응)
메시지 기록 (Message history) — /history를 통한 페이지 단위 브라우징
세션 대시보드 (Sessions dashboard) — /sessions 명령어로 상태 및 종료(kill) 버튼과 함께 모든 활성 세션 표시
지속적 상태 (Persistent state) — 바인딩(bindings) 및 읽기 오프셋(read offsets)이 봇 재시작 후에도 유지
graph TB
subgraph providers["Agent Providers"]
direction LR
...
토픽별 제공자 (Per-topic provider) — 서로 다른 토픽에서 동시에 서로 다른 에이전트(agents) 사용 가능
자동 감지 (Auto-detect) — 외부에서 생성된 창은 프로세스 이름(process name)을 통해 감지됨; pane 명령이 JS 런타임 래퍼(JS runtime wrapper, 예: node, bun)인 경우, 멀티플렉서 백엔드(multiplexer backend)를 통해 포그라운드 프로세스를 검사함 (tmux는 ps -t <tty>를 사용하고, herdr는 pane process-info를 읽음)
채팅 우선 (Chat-first) — 자연어 입력 → LLM이 셸 명령(shell command) 생성 → 한 번의 탭으로 승인 → 출력이 다시 스트리밍됨
원시 모드 (Raw mode) — ! 접두사를 사용하여 LLM을 우회하고 명령을 직접 전송
음성-명령 변환 (Voice-to-command) — Whisper를 통해 음성 메시지를 전사(transcribe)한 후 LLM을 통해 라우팅
위험한 명령 감지 (Dangerous command detection) — 파괴적인 명령을 실행하기 전 추가 확인 단계 제공
BYOK LLM — OpenAI, Anthropic, xAI, DeepSeek, Groq, Ollama (새로운 의존성 없음)
요구 사항:
Python 3.14+
tmux — 설치되어 있어야 하며 PATH에 포함되어야 함 (기본 백엔드; herdr를 사용하려면 CCGRAM_MULTIPLEXER=herdr 설정)
최소 하나 이상의 에이전트 CLI — claude (기본값), codex, gemini, 또는 pi가 설치 및 인증되어 있어야 함 (또는 추가 설치 없이 shell 사용)
uv tool install ccgram # 권장
pipx install ccgram # pipx
brew install alexei-led/tap/ccgram # Homebrew (macOS)
@BotFather를 통해 Telegram 봇 생성
BotFather 설정에서:
Allow Groups: On
Group Privacy: Off*(모든 토픽 메시지를 보기 위해 필요)
*Topics: On
토픽(Topics) 기능이 활성화된 Telegram 그룹에 봇 추가
Create Topics 및 Pin Messages 권한을 부여하여 봇을 관리자(Administrator)로 승격
~/.ccgram/.env 파일 생성:
TELEGRAM_BOT_TOKEN=your_bot_token_here
ALLOWED_USERS=your_telegram_user_id
CCGRAM_GROUP_ID=your_telegram_group_id
사용자 ID는 @userinfobot에서 확인할 수 있습니다. 그룹 ID는 @RawDataBot을 통해 확인하세요 (Peer ID 앞에 -100을 붙여야 합니다).
ccgram hook --install
자동 세션 추적(session tracking), 즉각적인 대화형 UI 감지(interactive UI detection), API 오류 알림(API error alerting), 그리고 서브 에이전트/팀 알림(subagent/team notifications)을 위해 Claude Code 훅(hooks)을 등록합니다. Codex, Gemini, 또는 Pi의 경우에는 필요하지 않습니다.
훅(hooks)이 누락된 경우, ccgram은 시작 시 수정 명령과 함께 경고를 표시합니다. 훅은 선택 사항이며, 터미널 스크래핑(terminal scraping)이 대체 수단(fallback)으로 작동합니다.
ccgram
Telegram 그룹을 열고, 새 토픽을 생성한 뒤 메시지를 보내면 디렉토리 브라우저가 나타납니다. 프로젝트 디렉토리를 선택하고, 에이전트(Claude, Codex, Gemini, Pi, 또는 Shell)를 선택한 뒤, 세션 모드(✅ Standard 또는 🚀 YOLO)를 선택하면 연결됩니다.
| 변수 / 플래그 (Variable / Flag) | 기본값 (Default) | 설명 (Description) |
|---|---|---|
TELEGRAM_BOT_TOKEN | (필수) | @BotFather로부터 받은 봇 토큰 (환경 변수 전용) |
ALLOWED_USERS | (필수) | 쉼표로 구분된 Telegram 사용자 ID |
CCGRAM_DIR | ~/.ccgram | 설정 및 상태 디렉토리 |
CCGRAM_PROVIDER | claude | 기본 제공자 (claude, codex, gemini, pi, shell) |
CCGRAM_<NAME>_COMMAND | (제공자로부터) | 제공자별 실행 명령 재정의 |
CCGRAM_MULTIPLEXER | tmux | 터미널 멀티플렉서 (Terminal multiplexer) 백엔드: tmux (기본값) 또는 herdr (설정 필요) |
CCGRAM_GROUP_ID | (모든 그룹) | 하나의 Telegram 그룹으로 제한 |
CCGRAM_STATUS_MODE | system | 토픽 이모지 색상 체계: system (초록색=작동 중) 또는 user (초록색=준비 완료) |
CCGRAM_HIDE_TOOL_CALLS | false | true로 설정 시 전역적으로 tool_use / tool_result 메시지를 숨김 (기본적으로 표시됨) |
CCGRAM_LLM_PROVIDER | (비활성화됨) | 셸 명령 생성 및 완료 요약을 위한 LLM |
CCGRAM_LLM_API_KEY | (비어 있음) | LLM API 키 (환경 변수 전용) |
CCGRAM_WHISPER_PROVIDER | (비활성화됨) | 음성 전사 (Voice transcription)를 위한 Whisper 제공자 (openai, groq) |
CCGRAM_TTS_PROVIDER | (비활성화됨) | 음성 답변을 위한 TTS 백엔드: edge (무료, 키 불필요) 또는 openai. edge를 사용하려면 pip install ccgram[tts]가 필요함 |
CCGRAM_TTS_VOICE | en-US-EmmaMultilingualNeural | 음성 이름. edge의 경우: 모든 edge-tts 음성. openai의 경우: alloy, nova, shimmer 등 |
CCGRAM_TTS_MODEL | gpt-4o-mini-tts | OpenAI TTS 모델. CCGRAM_TTS_PROVIDER=openai일 때만 사용됨 |
CCGRAM_TTS_API_KEY | (비어 있음) | OpenAI TTS를 위한 API 키 |
설정되지 않은 경우 OPENAI_API_KEY로 대체됨 |
| CCGRAM_LIVE_VIEW_INTERVAL | 5 | 라이브 뷰 새로고침 간격 (초) |
| CCGRAM_LIVE_VIEW_TIMEOUT | 300 | 라이브 뷰 자동 중지 제한 시간 (초) |
| CCGRAM_SEND_SEARCH_DEPTH | 5 | /send 파일 검색 시 최대 디렉토리 깊이 |
| CCGRAM_SEND_MAX_RESULTS | 50 | /send 검색 시 반환되는 최대 파일 결과 수 |
| AUTOCLOSE_DONE_MINUTES | 30 | N분 후 완료된 토픽 자동 종료 |
| AUTOCLOSE_DEAD_MINUTES | 10 | N분 후 비활성 세션 자동 종료 |
| CCGRAM_PANE_LIFECYCLE_NOTIFY | false | 창별 창(pane) 생성/종료 알림 기본값 |
| CCGRAM_MINIAPP_BASE_URL | (비활성화됨) | Mini App 대시보드를 위한 외부 접속 가능 HTTPS URL |
| CCGRAM_MINIAPP_HOST | 127.0.0.1 | Mini App 서버를 위한 로컬 aiohttp 바인드 호스트 |
| CCGRAM_MINIAPP_PORT | 8765 | Mini App 서버를 위한 로컬 aiohttp 바인드 포트 |
전체 참조: docs/guides.md
CCGram은 Telegram 인라인 버튼을 통해 열리고 Telegram의 WebApp 컨테이너 내부에서 실행되는 선택적 웹 대시보드를 제공합니다. v3.0에서는 세 가지 인터페이스를 사용할 수 있습니다:
Live terminal (라이브 터미널)— 연결된 멀티플렉서 창(multiplexer pane)의 xterm.js 스트림 (읽기 전용)
Transcript (트랜스크립트)— 전체 텍스트 검색이 가능한 페이지 단위의 세션 기록
Multi-pane grid (멀티 페인 그리드)— 창의 모든 창(pane)을 한 화면에 표시; 클릭하여 포커스 가능
Mini App은 기본적으로 비활성화되어 있습니다. CCGRAM_MINIAPP_BASE_URL이 설정되지 않으면 HTTP 서버와 대시보드 버튼 모두 노출되지 않습니다.
세 가지 Mini App 환경 변수를 설정합니다:
CCGRAM_MINIAPP_BASE_URL=https://ccgram.example.com CCGRAM_MINIAPP_HOST=127.0.0.1 CCGRAM_MINIAPP_PORT=8765
로컬 aiohttp 서버 앞단에서 TLS를 종료합니다 (cloudflared, caddy 또는 nginx 사용). 서버는 MINIAPP_HOST:MINIAPP_PORT에서 일반 HTTP로 리스닝하며, MINIAPP_BASE_URL에 지정된 공개 도메인은 반드시 HTTPS를 통해 이를 서비스해야 합니다. Telegram WebApps는 일반 HTTP를 거부합니다.
@BotFather에서:
/setdomain — 도메인 등록
/newapp — 동일한 URL을 가리키는 Mini App 항목 생성
ccgram 재시작
. 상태 버블(status bubble)에 새로운 "🪟 Dashboard" 버튼이 나타납니다.
토큰은 봇 토큰(bot token)으로 HMAC 서명되며, 단일 창(window) + 사용자(user) 범위로 제한되고 짧은 시간 내에 만료됩니다. 창 간 접근(cross-window access)은 허용되지 않으며, 모든 API 경로(route)는 호출 시마다 토큰을 검증합니다.
ccgram.example.com {
reverse_proxy 127.0.0.1:8765
}
nginx의 경우, 라이브 터미널 웹소켓(websocket)이 작동할 수 있도록 proxy_http_version 1.1과 표준 Upgrade 및 /Connection 헤더가 전달되도록 설정해야 합니다.
git clone https://github.com/alexei-led/ccgram.git
cd ccgram
uv sync --extra dev
...