telegram-copilot-bridge

Control GitHub Copilot CLI remotely from Telegram. Send prompts, manage sessions, and approve tool calls — all from your smartphone.

Architecture

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

Features

• Remote Prompting — Send Copilot prompts from Telegram, receive results on your phone

• Multi-Session — Run multiple Copilot sessions in parallel, switch between them

• Tool Approval — Approve or deny Copilot's tool calls via inline buttons

• Autopilot Mode — Auto-approve all tool calls for hands-free operation

• Session History — Resume past Copilot sessions with one tap

• Folder Picker — /new shows inline buttons for project directories

Installation

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

Prerequisites: Install Copilot CLI and authenticate:

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

Setup

1. Create a Telegram Bot

1. Open Telegram and message @BotFather

2. Send /newbot and follow the prompts

3. Copy the bot token

2. Get Your Chat ID and User ID

Send any message to your bot, then:

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

From the response, note:

• "chat": {"id": ...} → your Chat ID

• "from": {"id": ...} → your User ID (for the allowlist)

3. Configure

Copy the example file and fill in your values:

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

The .env file is loaded automatically on startup (from the current directory). Use TELEGRAM_ENV_FILE=/path/to/.env to point to a different location. Environment variables set in the shell always take priority over .env.

Usage

# 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 options:

Telegram Commands

Environment Variables

All variables can be set in .env or in the shell. Shell values take priority.

Telegram:

Copilot:

Security

• User allowlist: Only messages from TELEGRAM_ALLOWED_USERS are accepted. All other users are silently ignored.

• Timeouts: Configurable auto-shutdown timeout (default: no timeout). Permission requests timeout after 5 minutes (configurable via COPILOT_PERMISSION_TIMEOUT_SECONDS).

• No secrets in repo: All credentials via .env file or environment variables.

• Tool allowlist: Uses --allow-tool (not --allow-all-tools) to restrict what Copilot CLI can do.

• Directory restrictions: Restrict which directories Copilot sessions can operate in via COPILOT_ALLOWED_DIRS.

• Singleton lock: Only one instance can run per machine (TCP port lock).

Limitations

• VS Code local runs are not observable — There is no way to retrieve what Copilot is doing inside VS Code. MCP tools are one-way calls from VS Code → Bridge only.

• Status of CLI sessions started outside the Bridge is unavailable — If you launch copilot directly on the server, real-time execution status cannot be tracked. The Activity display in /status (estimated from events.jsonl modification time) is the only alternative.

• Tool approval requests from CLI sessions started outside the Bridge cannot be relayed — Only sessions launched via the Hub can relay tool approval requests through Telegram inline buttons.

• Single-instance restriction — Only one Hub process per machine (TCP port lock).

• Telegram message length limit — Responses exceeding 4000 characters are split automatically.

License

MIT