telegram-copilot-bridge

Telegram에서 원격으로 GitHub Copilot CLI를 제어하세요. 스마트폰에서 바로 프롬프트를 보내고, 세션을 관리하며, 도구 호출을 승인할 수 있습니다.

아키텍처

📱 Telegram
    ↕ (Bot API long-polling)
🐍 telegram-copilot-bridge
    ↕ (stdin/stdout NDJSON — ACP)
🤖 copilot --acp --stdio

Related MCP server: tsgram-mcp

기능

• 원격 프롬프팅 — Telegram에서 Copilot 프롬프트를 보내고 휴대폰으로 결과를 수신

• 다중 세션 — 여러 Copilot 세션을 병렬로 실행하고 전환

• 도구 승인 — 인라인 버튼을 통해 Copilot의 도구 호출을 승인하거나 거부

• 자동 조종 모드(Autopilot) — 핸즈프리 작업을 위해 모든 도구 호출을 자동 승인

• 세션 기록 — 탭 한 번으로 이전 Copilot 세션 재개

• 폴더 선택기 — /new 명령으로 프로젝트 디렉토리에 대한 인라인 버튼 표시

설치

git clone https://github.com/NobufumiMurata/telegram-copilot-bridge.git
cd telegram-copilot-bridge
pip install -e .

사전 요구 사항: Copilot CLI를 설치하고 인증하세요:

winget install GitHub.Copilot   # or: npm install -g @github/copilot
copilot                         # then /login to authenticate

설정

1. Telegram 봇 생성

1. Telegram을 열고 @BotFather에게 메시지를 보냅니다.

2. /newbot을 보내고 안내에 따릅니다.

3. 봇 토큰을 복사합니다.

2. 채팅 ID 및 사용자 ID 확인

봇에게 아무 메시지나 보낸 후 다음을 수행하세요:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates"

응답에서 다음을 확인합니다:

• "chat": {"id": ...} → 채팅 ID

• "from": {"id": ...} → 사용자 ID (허용 목록용)

3. 구성

예제 파일을 복사하고 값을 입력하세요:

cp .env.example .env

# .env
TELEGRAM_BOT_TOKEN=1234567890:AAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
TELEGRAM_CHAT_ID=-100000000000
TELEGRAM_ALLOWED_USERS=123456789

# Default AI model
COPILOT_MODEL=claude-opus-4.6

# Root folder for /dirs and /new folder picker
COPILOT_DIRS_ROOT=/home/user/projects

.env 파일은 시작 시(현재 디렉토리에서) 자동으로 로드됩니다. 다른 위치를 지정하려면 TELEGRAM_ENV_FILE=/path/to/.env를 사용하세요. 셸에 설정된 환경 변수가 .env보다 항상 우선합니다.

사용법

# Start (reads .env automatically)
python -m telegram_copilot_bridge

# With options
python -m telegram_copilot_bridge \
  --cwd /path/to/project \
  --model claude-opus-4.6 \
  --timeout 120 \
  -v

CLI 옵션:

Telegram 명령어

환경 변수

모든 변수는 .env 또는 셸에서 설정할 수 있습니다. 셸 값이 우선합니다.

Telegram:

Copilot:

보안

• 사용자 허용 목록: TELEGRAM_ALLOWED_USERS의 메시지만 허용됩니다. 다른 모든 사용자는 무시됩니다.

• 시간 제한: 구성 가능한 자동 종료 시간(기본값: 없음). 권한 요청은 5분 후 만료됩니다 (COPILOT_PERMISSION_TIMEOUT_SECONDS로 구성 가능).

• 저장소 내 비밀 정보 없음: 모든 자격 증명은 .env 파일이나 환경 변수를 통해 관리됩니다.

• 도구 허용 목록: --allow-tool을 사용하여 Copilot CLI가 수행할 수 있는 작업을 제한합니다.

• 디렉토리 제한: COPILOT_ALLOWED_DIRS를 통해 Copilot 세션이 작동할 수 있는 디렉토리를 제한합니다.

• 싱글톤 잠금: 머신당 하나의 인스턴스만 실행할 수 있습니다 (TCP 포트 잠금).

제한 사항

• VS Code 로컬 실행은 관찰 불가 — VS Code 내부에서 Copilot이 수행하는 작업을 가져올 방법이 없습니다. MCP 도구는 VS Code → Bridge 방향의 단방향 호출입니다.

• Bridge 외부에서 시작된 CLI 세션 상태는 확인 불가 — 서버에서 copilot을 직접 실행하면 실시간 실행 상태를 추적할 수 없습니다. /status의 활동 표시(events.jsonl 수정 시간으로 추정)가 유일한 대안입니다.

• Bridge 외부에서 시작된 CLI 세션의 도구 승인 요청은 중계 불가 — Hub를 통해 시작된 세션만 Telegram 인라인 버튼을 통해 도구 승인 요청을 중계할 수 있습니다.

• 단일 인스턴스 제한 — 머신당 하나의 Hub 프로세스만 가능 (TCP 포트 잠금).

• Telegram 메시지 길이 제한 — 4000자를 초과하는 응답은 자동으로 분할됩니다.

라이선스

MIT