telegram-copilot-bridge

Controla GitHub Copilot CLI de forma remota desde Telegram. Envía prompts, gestiona sesiones y aprueba llamadas a herramientas, todo desde tu smartphone.

Arquitectura

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

Related MCP server: mcp-telegram-claudecode

Características

• Prompting remoto — Envía prompts de Copilot desde Telegram, recibe los resultados en tu teléfono

• Sesiones múltiples — Ejecuta varias sesiones de Copilot en paralelo, cambia entre ellas

• Aprobación de herramientas — Aprueba o deniega las llamadas a herramientas de Copilot mediante botones integrados

• Modo piloto automático — Autoaprueba todas las llamadas a herramientas para una operación manos libres

• Historial de sesiones — Reanuda sesiones pasadas de Copilot con un toque

• Selector de carpetas — /new muestra botones integrados para los directorios del proyecto

Instalación

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

Requisitos previos: Instala Copilot CLI y autentícate:

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

Configuración

1. Crea un bot de Telegram

1. Abre Telegram y envía un mensaje a @BotFather

2. Envía /newbot y sigue las instrucciones

3. Copia el token del bot

2. Obtén tu ID de chat y tu ID de usuario

Envía cualquier mensaje a tu bot, luego:

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

De la respuesta, anota:

• "chat": {"id": ...} → tu ID de chat

• "from": {"id": ...} → tu ID de usuario (para la lista de permitidos)

3. Configura

Copia el archivo de ejemplo y rellena tus valores:

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

El archivo .env se carga automáticamente al iniciar (desde el directorio actual). Usa TELEGRAM_ENV_FILE=/ruta/al/.env para apuntar a una ubicación diferente. Las variables de entorno establecidas en el shell siempre tienen prioridad sobre .env.

Uso

# 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

Opciones de CLI:

Comandos de Telegram

Variables de entorno

Todas las variables se pueden establecer en .env o en el shell. Los valores del shell tienen prioridad.

Telegram:

Copilot:

Seguridad

• Lista de permitidos de usuario: Solo se aceptan mensajes de TELEGRAM_ALLOWED_USERS. Todos los demás usuarios son ignorados silenciosamente.

• Tiempos de espera: Tiempo de espera de apagado automático configurable (predeterminado: sin tiempo de espera). Las solicitudes de permiso caducan después de 5 minutos (configurable mediante COPILOT_PERMISSION_TIMEOUT_SECONDS).

• Sin secretos en el repositorio: Todas las credenciales se gestionan mediante el archivo .env o variables de entorno.

• Lista de permitidos de herramientas: Utiliza --allow-tool (no --allow-all-tools) para restringir lo que puede hacer Copilot CLI.

• Restricciones de directorio: Restringe los directorios en los que pueden operar las sesiones de Copilot mediante COPILOT_ALLOWED_DIRS.

• Bloqueo de instancia única: Solo se puede ejecutar una instancia por máquina (bloqueo de puerto TCP).

Limitaciones

• Las ejecuciones locales de VS Code no son observables — No hay forma de recuperar lo que Copilot está haciendo dentro de VS Code. Las herramientas MCP son llamadas unidireccionales solo desde VS Code → Bridge.

• El estado de las sesiones de CLI iniciadas fuera del Bridge no está disponible — Si inicias copilot directamente en el servidor, no se puede rastrear el estado de ejecución en tiempo real. La visualización de actividad en /status (estimada a partir de la hora de modificación de events.jsonl) es la única alternativa.

• Las solicitudes de aprobación de herramientas de sesiones de CLI iniciadas fuera del Bridge no se pueden retransmitir — Solo las sesiones iniciadas a través del Hub pueden retransmitir solicitudes de aprobación de herramientas a través de botones integrados de Telegram.

• Restricción de instancia única — Solo un proceso Hub por máquina (bloqueo de puerto TCP).

• Límite de longitud de mensajes de Telegram — Las respuestas que superan los 4000 caracteres se dividen automáticamente.

Licencia

MIT