vscode-copilot-telegram

Follow GitHub Copilot's work in VS Code from Telegram, and approve the shell commands it wants to run from your phone.

vscode-copilot-telegram is two small Python programs (Python 3.11+, Windows / macOS / Linux):

VS Code doesn't let other programs read or click Copilot's own "Allow?" pop-ups. So you turn off Copilot's built-in Run in Terminal tool, and run_command becomes the only way Copilot can run a command. If you don't approve a command, it doesn't run.

How it works

flowchart LR
    subgraph PC["Your computer"]
        subgraph VSC["VS Code"]
            CP["Copilot Chat<br/>(agent mode)"]
            BT["Built-in Run in Terminal<br/>(turned OFF)"]
        end
        MCP["vscode-copilot-telegram<br/>MCP server (stdio)"]
        SH["Shell in the<br/>workspace folder"]
        CS[("workspaceStorage/&lt;hash&gt;/<br/>chatSessions/*.json(l)")]
        W["vscode-copilot-telegram-watch"]
        AL[("Audit log<br/>(outside the project)")]
    end
    TG["Telegram Bot API<br/>api.telegram.org"]
    PH["Your phone<br/>(Telegram app)"]

    CP -- "run_command / ask_user / notify" --> MCP
    CP -. "not used" .-> BT
    MCP -- "sendMessage + buttons" --> TG
    TG -- "getUpdates: taps and replies" --> MCP
    MCP -- "only after Approve" --> SH
    MCP --> AL
    VSC -- "saves chat history" --> CS
    CS -- "reads" --> W
    W -- "sendMessage (prompts and replies)" --> TG
    TG <--> PH

1. Copilot (agent mode) calls run_command on the MCP server instead of its built-in terminal.

2. The server checks the block list, the allow list, and that the working folder is inside the workspace, then sends you a Telegram message with Approve / Deny / Deny with note buttons.

3. Your tap comes back through getUpdates. Only on Approve does the server run the command; the exit code and output go back to Copilot and a short tail goes to Telegram.

4. Separately, the watcher reads the chat history VS Code writes to disk and forwards each new message to the same Telegram chat.

Everything is outbound HTTPS to Telegram, so you don't need open ports, a public URL, or a webhook.

Related MCP server: Telegram Notify MCP Server

Features

• Approve commands on your phone. Each request shows the project, the command, the working folder, and Copilot's reason, with ✅ Approve, ❌ Deny, and 📝 Deny with note buttons. Your note goes back to Copilot.

• Fail closed. If you deny, don't answer before the timeout (10 minutes by default), Telegram can't be reached, or the server is misconfigured, the command doesn't run. The one exception: a command that matches your allow list still runs when Telegram can't be reached (the allow list is empty by default).

• Block list and allow list. Dangerous commands, like rm -rf / or a forced git push, are denied without asking. Commands you trust, like git status, can be auto-approved, and you still get a notice. You switch that on yourself with --accept-policy in your terminal, so an edit to the project file by Copilot can't turn it on. A command that chains other commands (;, &&, |, and similar) is never auto-approved.

• Only you can answer. Messages and taps from any other Telegram user are ignored. Each button works once, even after a restart.

• Secrets masked, everything logged. Tokens, keys, and passwords are masked before anything is sent to Telegram or written to the audit log (outside the project, in ~/.vscode-copilot-telegram/), which records every request and decision.

• Questions and chat mirror. Copilot can ask you a question with ask_user (answer buttons or a typed reply). The watcher sends your prompts and Copilot's replies to the same chat.

The details are in CONFIGURATION.md (block and allow lists, tools, and every option) and SECURITY.md (what is and isn't protected).

Quickstart

You need Python 3.11+, git, VS Code, and GitHub Copilot with agent mode. The full walkthrough for Windows and macOS, with every click, is in docs/SETUP.md.

1. Create a bot. In Telegram, send /newbot to @BotFather and copy the token. Send any message to @userinfobot to get your numeric id. Then open your new bot and tap Start.

2. Install (into its own folder, not inside your project):

   git clone https://github.com/weslylaboy/vscode-copilot-telegram.git
   cd vscode-copilot-telegram
   python3 -m venv .venv && source .venv/bin/activate      # Windows: py -3 -m venv .venv; .\.venv\Scripts\Activate.ps1
   pip install -e .

3. Save the credentials in ~/.config/vscode-copilot-telegram/.env (on Windows, C:\Users\YOU\.config\vscode-copilot-telegram\.env):

   TELEGRAM_BOT_TOKEN=123456789:AA...
   TELEGRAM_USER_ID=123456789

4. Test Telegram: vscode-copilot-telegram --test --workspace /path/to/your/project. It prints sent and you get a ✅ message.

5. Register the MCP server in your project. VS Code can run an agent chat with different harnesses. Two matter here: Local and Copilot (these docs call the second one the "Copilot harness"). You choose one in the Session Target picker, and each one reads a different file:

   • Local: copy examples/mcp.envfile.json to <project>/.vscode/mcp.json.

   • Copilot harness: copy examples/dot-mcp.json to <project>/.mcp.json.

   Create both files. Use a Local session while VS Code still has it, because there you can turn off Run in Terminal. VS Code plans to remove Local sessions; after that, use the Copilot harness (SETUP §7). In both files, set command to the full path of vscode-copilot-telegram in your venv (SETUP §8).

6. In Copilot Chat (agent mode): open Configure Tools, untick Run in Terminal, and tick vscode-copilot-telegram. Then run Chat: Manage Tool Approval and pre-approve the vscode-copilot-telegram tools. If a Copilot harness session doesn't let you untick Run in Terminal, use the settings in SETUP §7.

7. Tell Copilot to use the tools. Paste examples/copilot-instructions.md into <project>/.github/copilot-instructions.md.

8. Start the mirror: vscode-copilot-telegram-watch --workspace /path/to/your/project.

9. Try it: ask Copilot to "use run_command to run git status" and approve the request on your phone.

Then go through the verification checklist.

Documentation

Important limitations

Know these two before you rely on it: file edits aren't gated (Copilot writes files with its own edit tools, so review them with git diff and work on a branch), and the gate only works while Copilot's built-in Run in Terminal is off. The project also hasn't been tested yet against a live Telegram and a live VS Code; the open items are in To do. Which files in the project can change how the gate works is listed in SECURITY.md.

The full list is in ARCHITECTURE.md → Known limitations, and SECURITY.md shows what is and isn't gated.

To do

Open work, in three groups. More detail on the tests and the roadmap is in DEVELOPMENT.md.

Left to test

The automated tests use a fake Telegram and sample files. These still need a real run:

• Real Telegram: long polling, the 409 Conflict message, rate limits, how the messages look, the reply prompt for a deny note, and edits on old messages.

• Real VS Code and Copilot: Copilot uses run_command when Run in Terminal is off, tool approval works as described, the Copilot harness reads .mcp.json, and ${workspaceFolder} and envFile work on each OS.

• Real chat session files from a current VS Code on Windows, macOS, and VS Code Server (tunnels, SSH, WSL). Save small scrubbed samples as test fixtures.

• Windows: cmd.exe and PowerShell quoting in run_command, killing the whole process tree, and Task Scheduler with pythonw.exe.

• macOS: the launchd agent and the privacy prompts.

• Linux: the systemd user service.

• --accept-policy typed in a real terminal on Windows and Linux, and in the VS Code terminal (macOS was run by hand once).

• VS Code settings and MCP: the chat.tools.edits.autoApprove setting for the files that control the gate, and registering the server in the user-level MCP configuration (outside the project) so a project can't change its command. Details in DEVELOPMENT.md.

• The full verification checklist on each OS.

Left to do

• Add a preToolUse hook that blocks the built-in terminal, so the gate also holds in Copilot harness sessions. This matters more once VS Code removes Local sessions (SETUP §7).

• Approval for file edits (today only shell commands are gated).

• One poller shared by several VS Code windows, to remove the one-bot-per-window rule.

• Full paths for the shells on Windows (powershell, pwsh, cmd.exe, bash), so a file with that name in the project can't run in place of the real shell. taskkill already uses its full path.

• Publish to PyPI, so the install is pipx install vscode-copilot-telegram.

• Slack and Discord as other ways to approve.

To improve

Security notes that are missing from the docs:

• In the troubleshooting guide, use curl for deleteWebhook so the token doesn't stay in the browser history.

License

MIT © 2026 Wesly Laboy. See LICENSE.