🤖 Copilot Telegram Bot: A Secure, Mobile-First Agent in Your Pocket

This is a submission for the GitHub Copilot CLI Challenge

What I Built

copilot-telegram-bot - brings the power of GitHub Copilot to your smartphone. It transforms Telegram into a command center for your code, allowing you to architect, debug, and manage projects without ever opening a laptop.

The Problem

I often get my best coding ideas when I'm away from my desk—on the subway, in a coffee shop, or taking a walk. By the time I get to my computer, the context is lost. I needed a way to interact with my codebase securely and intelligently from my phone.

The Solution

I built a bridge between the Telegram Chat UI and GitHub Copilot CLI, powered by the github-copilot-sdk. This application embeds Copilot's agentic workflows, treating Telegram messages, taps, and image uploads as native context for the Copilot CLI.

🌟 Core Capabilities

• ⚙️ Dual Agent Modes:
  • Plan Mode: For brainstorming high-level architecture. It uses specialized prompts to act as a System Architect.
  • Edit Mode: The classic "Hands-on" developer experience for writing code and running terminal commands.
• 🔒 Sandboxed Workspace:
  • Project-First Workflow: Upon startup, users must select a specific project folder from their configured WORKSPACE_ROOT.
  • This ensures the agent is strictly confined to the chosen project context and cannot access unauthorized files on the host machine.
• 👁️ Total Observability:
  • Real-time Tool Usage: The bot displays every tool the agent uses (e.g., view - index.html, report_intent - Exploring codebase). You see exactly what the agent sees.
  • Cancel Anytime: If the agent goes down a rabbit hole, a /cancel command instantly kills the process, giving you full control over the session.
• 🛡️ Human-in-the-Loop Security (The Permission Bridge):
  • This is the core technical innovation. The bot intercepts "dangerous" tool calls from the SDK (like bash or create).
  • Instead of auto-executing, it renders a Telegram Inline Keyboard. You tap "Allow" or "Deny" instantly. It brings enterprise-grade control to a chat interface.
• 👀 Multimodal Vision: Snap a photo of a whiteboard sketch or a UI mockup, send it to the chat, and watch Copilot convert pixels into boilerplate code.
• 📊 Developer HUD: Every response includes a "Heads-Up Display" footer showing your current Git branch, dirty state, active model, and cost multiplier.

Available commands

Tech Stack

• Python 3.10+: Fully async implementation with modern Python features.
• github-copilot-sdk (v0.1.23): The official SDK for Copilot CLI integration.
• python-telegram-bot (v20+): A robust async wrapper for the Telegram Bot API.
• uv: A fast and lightweight Python package manager.

Demo

The following workflow highlights a typical session, demonstrating how the bot assists with planning, coding, and project management directly from Telegram:

Start Message: The bot greets the user and prompts for project selection.

Greeting: A quick connectivity test with the model.

Plan Mode: Switching to Plan Mode to brainstorm a game architecture.

Edit Mode: Switching back to Edit Mode to implement the plan.

Execute Commands: Committing and pushing changes to GitHub via chat.

Multimodal Uploads: Uploading a UI sketch for analysis. Images are securely stored in a temporary session directory and auto-cleared upon session termination.

More Implementation: I describe the desired feature in plain text. The agent analyzes the request, plans the changes, and implements the code.

Seamless Branching & Pushing: Upon receiving user permission, the bot executes the git commands (branch creation, commit, push) and the session HUD updates instantly to reflect the new branch state.

Model Selection: Swapping Copilot models and its reasoning effort via inline keyboard.

Permission Control: Approving risky operations (Human-in-the-Loop).

Interactive Options: Replying to agent clarification requests via buttons.

File Management: Navigating the file system with ls and cwd.

Session Management: Managing active sessions via /session.

Session Sharing: Exporting the full chat history to Markdown via /share.

My Experience with GitHub Copilot CLI

It was genuinely fun to work with the github-copilot-sdk and get a "behind-the-scenes" look at how the Copilot CLI orchestrates agents. Building copilot-telegram-bot was an exercise in deconstructing and reconstructing the Copilot CLI experience for mobile.

Workflow Philosophy & Mobile Optimization

My experience with the Copilot CLI taught me that the "Plan before Execute" step is critical—verifying the agent's approach often saves hours of debugging later. I ported this workflow to the bot but quickly realized that standard CLI output is often too dense for a chat interface.

To solve this, I engineered specific system prompts for both Plan and Edit modes, injecting rules like Response must be PLAIN TEXT and Keep it scannable to force the model into brevity. This constrains the output to short, high-signal bullet points instead of verbose technical descriptions. Whether I'm reviewing an architectural plan or a debugging summary, the content remains readable on a phone screen while walking, maintaining the rigor of the CLI without the visual clutter of a terminal.

Exploring the SDK

I treated the Copilot CLI as a live reference implementation. Observing the raw event stream—watching how the agent decides to call tools, manage context, and handle state—was a fascinating experience in reverse-engineering. It felt like I was decoding the DNA of the CLI to rebuild it for a new platform.

UX Design & Feature Philosophy

I wanted to capture the spirit of the Copilot CLI's command design—which prioritizes context, structure, and control—and translate it into a mobile-first experience. I cherry-picked features that I felt would best enhance the UX in a chat environment:

• Context Awareness & Control: The CLI builds trust by showing you exactly what it's doing line-by-line. To replicate this "glass box" experience, I enforced a Project-First Workflow (sandboxing the agent to a specific directory) and implemented Real-time Tool Usage Response. The user sees every file the agent reads and every command it attempts as a stream of chat responses, with the ability to /cancel immediately. This transparency, paired with the HUD footer (displaying active branch, dirty state, and model), ensures the developer maintains full situational awareness and control, just like in a terminal.
• Mobile-First Interactions: Actions like model selection (/model with cost info) or permission approvals are converted into tap-friendly buttons to minimize typing.
• Visual Context (Beyond Text): The standard CLI is limited to text input, but development is often visual. I utilized Telegram's native media handling to enable Multimodal Support. Users can upload images (like UI sketches or bug screenshots), which are sandboxed in a temporary server directory for the agent to analyze. This adds a visual dimension to the Copilot experience that a traditional terminal simply cannot offer.
• Session Review: Similar to reviewing terminal logs, the /share command allows users to export the full session to Markdown, bridging the gap between quick mobile chats and deep desktop review.

Link

Github Repository: copilot-telegram-bot