alexei-led/ccgram

휴대전화로 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 키

전체 참조: 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
...

alexei-led/ccgram

요약

핵심 포인트

댓글