Copilot Telegram Bot

Remote-first operational control layer for GitHub Copilot CLI via Telegram.

This project runs locally on your machine and exposes a controlled Telegram interface for interacting with your Copilot CLI session.

⚠️ This bot executes actions against your local workspace. Use only in trusted environments and review security settings carefully.

❓ Why this project?

GitHub Copilot CLI is great in-terminal, but this project adds a remote operational layer for moments when you are not at your desk.

Use this when you need to:

• Run and supervise coding tasks from mobile/Telegram.
• Keep a controlled workflow with approval steps via Plan Mode.
• Operate with explicit guardrails (path allowlists, owner permissions, executable allowlists, timeouts).
• Extend workflows through MCP servers without leaving your chat interface.

Why use this instead of regular Copilot CLI usage?

• Regular Copilot CLI: local-first, interactive terminal flow.
• Copilot Telegram Bot: remote-first control, operational visibility, and approval-oriented execution from Telegram.

Both are complementary: this bot is designed for remote execution, monitoring, and controlled delegation.

👤 Deployment Scope

Designed for controlled single-user environments. It is not designed for public multi-tenant deployment without additional hardening.

🧩 Real Use Cases

• Remote coding supervision: launch and monitor tasks while away from your workstation.
• Mobile-first triage: review logs/status and unblock issues quickly from Telegram.
• Plan approval workflow: generate implementation plans and explicitly approve before execution.
• Cross-repo operations: switch projects and control MCP-enabled workflows in one place.

✨ Features

• 🤖 GitHub Copilot Integration - Powered by official @github/copilot-sdk
• 📱 Telegram Bot Interface - Control Copilot remotely via grammY bot framework
• 🔌 MCP Server Support - Model Context Protocol integration (STDIO & HTTP)
• 🔒 Security Features - Path allowlist, executable validation, data sanitization
• 🎯 Plan Mode - Generate implementation plans and explicitly approve them before execution ⚡
• 🌐 Cross-Platform - Windows, Linux, macOS support

🔐 Security Philosophy

This project is designed around explicit control and guardrails:

• Path allowlists
• Owner-based permissions
• Executable allowlists
• Time-bounded operations

📌 Project Status

• Actively maintained
• Production-usable for controlled environments
• Open to feedback and contributions

🏗️ Architecture (high-level)

flowchart LR
    U[User in Telegram] --> B[Copilot Telegram Bot]
    B --> C[GitHub Copilot CLI / SDK]
    C --> W[Local Project Workspace]
    C --> M[MCP Servers - STDIO / HTTP]
    B --> L[Logs & Session State]

🖼️ Product Walkthrough

1) Help command

2) Plan mode + ask_user flow

3) Plan completion message

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• GitHub Copilot subscription (required)
• Telegram Bot Token from @BotFather
• Copilot CLI installed globally:

  npm install -g @github/copilot
  copilot
  # Then run: /login

Installation

# Clone repository
git clone https://github.com/Rios-Guerrero-Juan-Manuel/copilot-telegram-bot.git
cd copilot-telegram-bot

# Install dependencies
npm install

# Configure environment (Linux/macOS)
cp .env.example .env
# Edit .env with your credentials

# Configure environment (Windows PowerShell)
Copy-Item .env.example .env
# Edit .env with your credentials

Global installation (CLI)

# Install globally from npm
npm install -g @juan-manuel-rios-guerrero/copilot-telegram-bot

# Run the bot CLI
copilot-telegram-bot

Configuration

Create a .env file with the following:

# Required
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
TELEGRAM_CHAT_ID=your_telegram_user_id

# Paths
DEFAULT_PROJECT_PATH=/path/to/your/project
ALLOWED_PATHS=/path/to/your/project,/other/allowed/path

# Optional (see .env.example for full list)
LOG_LEVEL=info
COPILOT_OPERATION_TIMEOUT=1200000

Running

# Development mode (auto-reload)
npm run dev

# Production mode
npm start

# Build TypeScript
npm run build

# Run tests
npm test

📦 Available npm Scripts

Development & Build

npm run dev          # Development mode with auto-reload
npm start            # Production mode
npm run build        # Compile TypeScript
npm run lint         # Run ESLint
npm run setup        # Initial setup (.env + install)

Testing

npm test                      # Full test suite
npm run test:coverage         # Tests with coverage report
npm run test:e2e              # End-to-end integration tests
npm run test:security         # Security tests
npm run test:all-checks       # Type check + full test suite
npm run test:regression       # Regression test suite
npm run test:regression:coverage  # Regression tests with coverage

For Unix systems, additional setup scripts are available in scripts/:

• ./scripts/setup.sh - Quick project setup
• ./scripts/install-mcp.sh - Interactive MCP server configuration
• ./scripts/setup-mcp-example.sh - Quick MCP setup

📚 Documentation

• Full Setup Guide - Detailed installation and configuration
• Contributing Guide - Development guidelines and best practices

📋 Commands Reference

Information Commands

| Command | Description | |---------|-------------| | /start | Initialize bot and show current status | | /help | Display available commands | | /status | Show current model, project, and active sessions | | /logs [n] | View last n lines of logs (owner only) | | /language | Change bot language |

Navigation & Projects

| Command | Description | Interactive Mode | |---------|-------------|------------------| | /pwd | Print current working directory | - | | /ls | List files in current directory | - | | /cd [path] | Change directory (or start wizard) | ✅ Interactive navigation | | /allowpath <path> | Add allowed path (admin only) | - | | /projects | List saved projects | - | | /addproject [alias] [path] | Save project (or start wizard) | ✅ Step-by-step guidance | | /rmproject <alias> | Remove saved project | - | | /switch [alias] | Switch to saved project | ✅ Interactive menu |

Copilot & Model

| Command | Description | |---------|-------------| | /plan <task> | Start plan mode (interactive approval) | | /showplan | Show active plan | | /editplan [id] | Export plan as editable file and wait for updated .md upload | | /exportplan [id] | Export plan as .md file | | /plans | List saved plans | | /exitplan | Exit plan mode | | /model | Change LLM model (interactive menu) | | /stop | Cancel current operation | | /extend | Extend operation timeout | | /new_chat | Start a clean chat session | | /reset | Alias for /new_chat |

MCP Servers

| Command | Description | |---------|-------------| | /mcp | List MCP servers and quick actions | | /mcp add <name> <http\|stdio> <url\|command> [args...] | Add MCP server directly (non-wizard mode) | | /mcp remove <name> | Remove MCP server | | /mcp enable <name> | Enable MCP server | | /mcp disable <name> | Disable MCP server | | /mcp refresh | Reload MCP configuration | | /mcp_add | Add MCP server (interactive wizard) | | /mcp_list [page] | List servers with pagination | | /mcp_delete <name> | Delete MCP server |

Examples

# Simple question
"What is the purpose of this function?"

# Complex task
"/plan Implement OAuth2 authentication with Google sign-in"

# Navigate to project
/cd /path/to/my/project

# Or use interactive wizard
/cd
# Then click through directories

# Add project with wizard
/addproject
# Follow step-by-step guidance

# Switch models
/model
# Select from interactive menu

⚙️ Configuration

Environment Variables

All configuration is done via .env file. See .env.example for complete list.

Required

TELEGRAM_BOT_TOKEN=your_bot_token           # From @BotFather
TELEGRAM_CHAT_ID=your_telegram_user_id      # From @userinfobot
DEFAULT_PROJECT_PATH=/path/to/project       # Default working directory
ALLOWED_PATHS=/path1,/path2                 # Security: allowed directories

Security Settings

# Path allowlist (comma-separated)
ALLOWED_PATHS=/home/user/projects,/opt/apps

# MCP executable allowlist (comma-separated)
ALLOWED_MCP_EXECUTABLES=npx,node,python,python3

# Owner permissions
ALLOWED_TELEGRAM_IDS=123456789,987654321

Timeouts & Retries

# Operation timeout (default: 20 minutes)
COPILOT_OPERATION_TIMEOUT=1200000

# User response timeout (default: 5 minutes)
ASK_USER_TIMEOUT=300000

# Network retry settings
TELEGRAM_RETRY_INITIAL_DELAY_MS=1000
TELEGRAM_RETRY_MAX_DELAY_MS=32000

Logging

# Log level: debug | info | warn | error
LOG_LEVEL=info

# Rotation settings
LOG_MAX_SIZE=20m
LOG_MAX_FILES=14d
LOG_DIR=./logs

MCP Server Configuration

MCP servers are configured per-user in the SQLite database. Use the /mcp_add wizard or manually edit:

STDIO Server Example:

{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
}

HTTP Server Example:

{
  "type": "http",
  "url": "https://api.example.com/mcp/"
}

🌐 Platform Support

Compatible with Windows, Linux, and macOS. Requires Node.js >= 18.0.0.

CI validates on all three platforms:

• install/build/test
• better-sqlite3 smoke test
• npm package install + CLI command startup smoke (copilot-telegram-bot)

See SETUP.md for platform-specific installation instructions.

🤖 Supported Models

Use /model command to select from available models (GPT-4, Claude, Gemini, etc.).

Note: Available models depend on your GitHub Copilot subscription.

🐛 Troubleshooting

Common Issues

Bot doesn't start:

# Check logs (Linux/macOS)
cat logs/error-*.log | tail -n 50

# Verify environment variables (Linux/macOS)
cat .env

# Test Copilot CLI
copilot
# Run: /login

# Check logs (Windows PowerShell)
Get-Content -Path logs\error-*.log -Tail 50

# Verify environment variables (Windows PowerShell)
Get-Content .env

# Test Copilot CLI
copilot
# Run: /login

Copilot CLI not authenticated:

copilot
# Run: /login

Path permission errors:

• Verify ALLOWED_PATHS includes the directory
• Check DEFAULT_PROJECT_PATH exists
• Use absolute paths only

See SETUP.md for detailed troubleshooting.

🤝 Contributing

See CONTRIBUTING.md for guidelines.

📄 License

Apache 2.0 - see LICENSE file.